@ethersphere/bee-js 9.8.0 → 10.0.0

package/dist/mjs/bee.js

@@ -40,21 +40,23 @@ import { asNumberString, assertData, assertFileData, makeTagUid, prepareAllTagsO
 import { BatchId, EthAddress, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Span, Topic, TransactionId } from "./utils/typed-bytes.js";
 import { assertBeeUrl, stripLastSlash } from "./utils/url.js";
 /**
- * The main component that abstracts operations available on the main Bee API.
+ * The main component that abstracts operations available on the Bee API.
  *
- * Not all methods are always available as it depends in what mode is Bee node launched in.
- * For example gateway mode and light node mode has only limited set of endpoints enabled.
+ * Instantiate with `new Bee(url, options)` where `url` is the Bee node URL and `options` are optional parameters.
+ *
+ * @example
+ * const bee = new Bee('http://localhost:1633')
  */
 export class Bee {
   /**
    * @param url URL on which is the main API of Bee node exposed
    * @param options
+   *
+   * @example
+   * const bee = new Bee('http://localhost:1633')
    */
   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);
     if (options?.signer) {
       this.signer = new PrivateKey(options.signer);
@@ -70,15 +72,19 @@ export class Bee {
     };
   }
   /**
-   * Upload data to a Bee node
+   * Uploads raw data to the network (as opposed to uploading chunks or files).
    *
-   * @param postageBatchId Postage BatchId to be used to upload the data with
-   * @param data    Data to be uploaded
-   * @param options Additional options like tag, encryption, pinning, content-type and request options
+   * Data uploaded with this method should be retrieved with the {@link downloadData} method.
+   *
+   * @param postageBatchId Usable Postage Batch ID with sufficient capacity to upload the data.
+   * @param data           A `string` (text data) or `Uint8Array` (raw data) to be uploaded.
+   * @param options        Additional options like tag, encryption, pinning, content-type and request options.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @returns reference is a content hash of the data
-   * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
+   *
    * @see [Bee API reference - `POST /bytes`](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes/post)
+   * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
    */
   async uploadData(postageBatchId, data, options, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
@@ -89,21 +95,32 @@ export class Bee {
     return bytes.upload(this.getRequestOptionsForCall(requestOptions), data, postageBatchId, options);
   }
   /**
-   * Requests content length for a `/bytes` reference
+   * Fetches content length for a `/bytes` reference.
+   *
+   * @param reference
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
-   * @see [Bee API reference - `HEAD /bytes/`](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes~1%7Breference%7D/head)
+   * @see [Bee API reference - `HEAD /bytes/{reference}`](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes~1%7Breference%7D/head)
    */
-  async probeData(reference, options) {
+  async probeData(reference, requestOptions) {
     reference = new Reference(reference);
-    return bytes.head(this.getRequestOptionsForCall(options), reference);
+    return bytes.head(this.getRequestOptionsForCall(requestOptions), reference);
   }
   /**
-   * Download data as a byte array
+   * Downloads raw data through the `GET /bytes/{reference}` endpoint.
    *
-   * @param resource Swarm reference, Swarm CID, or ENS domain
+   * This method may be used to download data that was uploaded with the {@link uploadData} method.
+   *
+   * For downloading files or using the `GET /bzz/{reference}/` endpoint, use the {@link downloadFile} method instead.
+   * For downloading chunks or using the `GET /chunks/{reference} endpoint, use the `downloadChunk` method instead.
+   *
+   * @param resource Swarm reference, Swarm CID, or ENS domain.
    * @param options Options that affects the request behavior
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
    * @throws TypeError if some of the input parameters is not expected type
    * @throws BeeArgumentError if there is passed ENS domain with invalid unicode characters
+   *
    * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
    * @see [Bee API reference - `GET /bytes`](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes~1{reference}/get)
    */
@@ -114,12 +131,18 @@ export class Bee {
     return bytes.download(this.getRequestOptionsForCall(requestOptions), new ResourceLocator(resource), options);
   }
   /**
-   * Download data as a Readable stream
+   * Download raw data through the `GET /bytes/{reference}` endpoint.
+   *
+   * This method may be used to download data that was uploaded with the {@link uploadData} method.
+   *
+   * Only tested in Node.js environment.
+   *
+   * @param resource Swarm reference, Swarm CID, or ENS domain.
+   * @param options Options that affects the request behavior.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
+   * @returns ReadableStream of Uint8Array
    *
-   * @param resource Swarm reference, Swarm CID, or ENS domain
-   * @param options Options that affects the request behavior
-   * @throws TypeError if some of the input parameters is not expected type
-   * @throws BeeArgumentError if there is passed ENS domain with invalid unicode characters
    * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
    * @see [Bee API reference - `GET /bytes`](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes~1{reference}/get)
    */
@@ -130,11 +153,14 @@ export class Bee {
     return bytes.downloadReadable(this.getRequestOptionsForCall(requestOptions), new ResourceLocator(resource), options);
   }
   /**
-   * Upload chunk to a Bee node
+   * Uploads a chunk to the network.
    *
-   * @param postageBatchId Postage BatchId to be used to upload the chunk with
+   * Chunks uploaded with this method should be retrieved with the {@link downloadChunk} method.
+   *
+   * @param stamp Postage Batch ID or an Envelope created with the {@link createEnvelope} method.
    * @param data    Raw chunk to be uploaded
    * @param options Additional options like tag, encryption, pinning, content-type and request options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @returns reference is a content hash of the data
    * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
@@ -154,12 +180,17 @@ export class Bee {
     return chunk.upload(this.getRequestOptionsForCall(requestOptions), data, stamp, options);
   }
   /**
-   * Download chunk as a byte array
+   * Downloads a chunk as a `Uint8Array`.
+   *
+   * May be used to download chunks uploaded with the {@link uploadChunk} method.
+   *
+   * Use {@link downloadData} method to download raw data uploaded with the {@link uploadData} method.
+   * Use {@link downloadFile} method to download files uploaded with the {@link uploadFile} method.
    *
    * @param reference Bee chunk reference in hex string (either 64 or 128 chars long) or ENS domain.
    * @param options Options that affects the request behavior
-   * @throws TypeError if some of the input parameters is not expected type
-   * @throws BeeArgumentError if there is passed ENS domain with invalid unicode characters
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
    * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
    * @see [Bee API reference - `GET /chunks`](https://docs.ethswarm.org/api/#tag/Chunk/paths/~1chunks~1{address}/get)
    */
@@ -173,7 +204,7 @@ export class Bee {
   /**
    * Create a grantees list from the given array of public keys.
    *
-   * The grantees list can be obtained with the `getGrantees` method.
+   * The grantees list can be obtained with the {@link getGrantees} method.
    *
    * @param postageBatchId - The ID of the postage batch.
    * @param grantees - An array of public keys representing the grantees.
@@ -203,7 +234,7 @@ export class Bee {
    * @param history - The history.
    * @param postageBatchId - The ID of the postage batch.
    * @param grantees - The grantees.
-   * @param requestOptions - Optional request options.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    * @returns A Promise that resolves to to a `GranteesResult` object.
    */
   async patchGrantees(postageBatchId, reference, history, grantees, requestOptions) {
@@ -217,12 +248,18 @@ export class Bee {
     return grantee.patchGrantees(postageBatchId, reference, history, publicKeys, this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Upload single file to a Bee node.
+   * Uploads a single file to a Bee node.
+   *
+   * To download the file, use the {@link downloadFile} method.
+   *
+   * Use {@link uploadData} method to upload raw data that can be downloaded with the {@link downloadData} method.
+   * Use {@link uploadChunk} method to upload chunks that can be downloaded with the {@link downloadChunk} method.
    *
    * @param postageBatchId Postage BatchId to be used to upload the data with
    * @param data    Data or file to be uploaded
    * @param name    Optional name of the uploaded file
    * @param options Additional options like tag, encryption, pinning, content-type and request options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
@@ -252,14 +289,13 @@ export class Bee {
     }
   }
   /**
-   * Download single file.
+   * Downloads a single file.
    *
-   * @param resource Swarm reference, Swarm CID, or ENS domain
+   * @param resource Swarm reference, Swarm CID, or ENS domain.
    * @param path If reference points to manifest, then this parameter defines path to the file
    * @param options Options that affects the request behavior
-   * @throws TypeError if some of the input parameters is not expected type
-   * @throws BeeArgumentError if there is passed ENS domain with invalid unicode characters
-   * @see Data
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
    * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
    * @see [Bee API reference - `GET /bzz`](https://docs.ethswarm.org/api/#tag/BZZ/paths/~1bzz~1%7Breference%7D~1%7Bpath%7D/get)
    */
@@ -275,8 +311,7 @@ export class Bee {
    * @param reference Bee file reference in hex string (either 64 or 128 chars long), ENS domain or Swarm CID.
    * @param path If reference points to manifest / collections, then this parameter defines path to the file
    * @param options Options that affects the request behavior
-   * @throws TypeError if some of the input parameters is not expected type
-   * @throws BeeArgumentError if there is passed ENS domain with invalid unicode characters
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
    * @see [Bee API reference - `GET /bzz`](https://docs.ethswarm.org/api/#tag/BZZ/paths/~1bzz~1%7Breference%7D~1%7Bpath%7D/get)
@@ -299,6 +334,7 @@ export class Bee {
    * @param postageBatchId Postage BatchId to be used to upload the data with
    * @param fileList list of files to be uploaded
    * @param options Additional options like tag, encryption, pinning and request options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee docs - Upload directory](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download#upload-a-directory)
@@ -312,13 +348,57 @@ export class Bee {
     const data = makeCollectionFromFileList(fileList);
     return bzz.uploadCollection(this.getRequestOptionsForCall(requestOptions), data, postageBatchId, options);
   }
+  /**
+   * Hashes a directory locally and returns the root hash (Swarm reference).
+   *
+   * The actual Swarm reference may be different as there is no canonical hashing of directories.
+   * For example, metadata may have different casing, or the order of metadata may differ.
+   * Such small differences will result in different Swarm references.
+   *
+   * Different implementations of the Mantaray structure may also result in different Swarm references.
+   *
+   * @param dir
+   * @returns
+   */
   async hashDirectory(dir) {
     return hashDirectory(dir);
   }
+  /**
+   * Uploads a directory to the network. The difference between this method and {@link uploadFilesFromDirectory} is that
+   * this method streams the directory contents directly to the Bee node, which supports arbitrary directory sizes,
+   * but may be slower due to uploading chunks one by one.
+   *
+   * Options such as encryption, erasure coding and ACT are not yet available for this method.
+   *
+   * Only intended for the Node.js environment.
+   *
+   * @param postageBatchId
+   * @param dir
+   * @param onUploadProgress
+   * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
   async streamDirectory(postageBatchId, dir, onUploadProgress, options, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
     return streamDirectory(this, dir, postageBatchId, onUploadProgress, options, this.getRequestOptionsForCall(requestOptions));
   }
+  /**
+   * Uploads a collection of files to the network. The difference between this method and {@link uploadFiles} is that
+   * this method streams the files to the Bee node, which supports arbitrary sizes,
+   * but may be slower due to uploading chunks one by one.
+   *
+   * Options such as encryption, erasure coding and ACT are not yet available for this method.
+   *
+   * Only intended for the browser environment.
+   *
+   * @param postageBatchId
+   * @param files
+   * @param onUploadProgress
+   * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
   async streamFiles(postageBatchId, files, onUploadProgress, options, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
     return streamFiles(this, files, postageBatchId, onUploadProgress, options, this.getRequestOptionsForCall(requestOptions));
@@ -366,23 +446,23 @@ export class Bee {
     return bzz.uploadCollection(this.getRequestOptionsForCall(requestOptions), data, postageBatchId, options);
   }
   /**
-   * Create a new Tag which is meant for tracking progres of syncing data across network.
+   * Creates a new Tag which is meant for tracking upload and synchronization progress.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
-   * @param options Options that affects the request behavior
    * @see [Bee docs - Syncing / Tags](https://docs.ethswarm.org/docs/develop/access-the-swarm/syncing)
    * @see [Bee API reference - `POST /tags`](https://docs.ethswarm.org/api/#tag/Tag/paths/~1tags/post)
    */
-  async createTag(options) {
-    return tag.createTag(this.getRequestOptionsForCall(options));
+  async createTag(requestOptions) {
+    return tag.createTag(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Fetches all tags.
+   * Fetches all tags in a paginated manner.
    *
    * The listing is limited by options.limit. So you have to iterate using options.offset to get all tags.
    *
-   * @param options Options that affects the request behavior
-   * @throws TypeError if limit or offset are not numbers or undefined
-   * @throws BeeArgumentError if limit or offset have invalid options
+   * @param options Specify `limit` and `offset` to paginate through the tags.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Syncing / Tags](https://docs.ethswarm.org/docs/develop/access-the-swarm/syncing)
    * @see [Bee API reference - `GET /tags`](https://docs.ethswarm.org/api/#tag/Tag/paths/~1tags/get)
@@ -394,34 +474,31 @@ export class Bee {
     return tag.getAllTags(this.getRequestOptionsForCall(requestOptions), options?.offset, options?.limit);
   }
   /**
-   * Retrieve tag information from Bee node
+   * Retrieves tag information from Bee node.
    *
    * @param tagUid UID or tag object to be retrieved
-   * @param options Options that affects the request behavior
-   * @throws TypeError if tagUid is in not correct format
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Syncing / Tags](https://docs.ethswarm.org/docs/develop/access-the-swarm/syncing)
    * @see [Bee API reference - `GET /tags/{uid}`](https://docs.ethswarm.org/api/#tag/Tag/paths/~1tags~1{uid}/get)
    *
    */
-  async retrieveTag(tagUid, options) {
+  async retrieveTag(tagUid, requestOptions) {
     tagUid = makeTagUid(tagUid);
-    return tag.retrieveTag(this.getRequestOptionsForCall(options), tagUid);
+    return tag.retrieveTag(this.getRequestOptionsForCall(requestOptions), tagUid);
   }
   /**
-   * Delete Tag
+   * Deletes Tag.
    *
    * @param tagUid UID or tag object to be retrieved
-   * @param options Options that affects the request behavior
-   * @throws TypeError if tagUid is in not correct format
-   * @throws BeeResponse error if something went wrong on the Bee node side while deleting the tag.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Syncing / Tags](https://docs.ethswarm.org/docs/develop/access-the-swarm/syncing)
    * @see [Bee API reference - `DELETE /tags/{uid}`](https://docs.ethswarm.org/api/#tag/Tag/paths/~1tags~1{uid}/delete)
    */
-  async deleteTag(tagUid, options) {
+  async deleteTag(tagUid, requestOptions) {
     tagUid = makeTagUid(tagUid);
-    return tag.deleteTag(this.getRequestOptionsForCall(options), tagUid);
+    return tag.deleteTag(this.getRequestOptionsForCall(requestOptions), tagUid);
   }
   /**
    * Update tag's total chunks count.
@@ -431,99 +508,90 @@ export class Bee {
    *
    * @param tagUid UID or tag object to be retrieved
    * @param reference The root reference that contains all the chunks to be counted
-   * @param options Options that affects the request behavior
-   * @throws TypeError if tagUid is in not correct format
-   * @throws BeeResponse error if something went wrong on the Bee node side while deleting the tag.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Syncing / Tags](https://docs.ethswarm.org/docs/develop/access-the-swarm/syncing)
    * @see [Bee API reference - `PATCH /tags/{uid}`](https://docs.ethswarm.org/api/#tag/Tag/paths/~1tags~1{uid}/patch)
    */
-  async updateTag(tagUid, reference, options) {
+  async updateTag(tagUid, reference, requestOptions) {
     reference = new Reference(reference);
     tagUid = makeTagUid(tagUid);
-    return tag.updateTag(this.getRequestOptionsForCall(options), tagUid, reference);
+    return tag.updateTag(this.getRequestOptionsForCall(requestOptions), tagUid, reference);
   }
   /**
-   * Pin local data with given reference
+   * Pins local data with given reference.
    *
    * @param reference Data reference
-   * @param options Options that affects the request behavior
-   * @throws TypeError if reference is in not correct format
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Pinning](https://docs.ethswarm.org/docs/develop/access-the-swarm/pinning)
    */
-  async pin(reference, options) {
+  async pin(reference, requestOptions) {
     reference = new Reference(reference);
-    return pinning.pin(this.getRequestOptionsForCall(options), reference);
+    return pinning.pin(this.getRequestOptionsForCall(requestOptions), reference);
   }
   /**
-   * Unpin local data with given reference
+   * Unpins local data with given reference.
    *
    * @param reference Data reference
-   * @param options Options that affects the request behavior
-   * @throws TypeError if reference is in not correct format
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Pinning](https://docs.ethswarm.org/docs/develop/access-the-swarm/pinning)
    */
-  async unpin(reference, options) {
+  async unpin(reference, requestOptions) {
     reference = new Reference(reference);
-    return pinning.unpin(this.getRequestOptionsForCall(options), reference);
+    return pinning.unpin(this.getRequestOptionsForCall(requestOptions), reference);
   }
   /**
-   * Get list of all locally pinned references
+   * Gets list of all locally pinned references.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
-   * @param options Options that affects the request behavior
    * @see [Bee docs - Pinning](https://docs.ethswarm.org/docs/develop/access-the-swarm/pinning)
    */
-  async getAllPins(options) {
-    return pinning.getAllPins(this.getRequestOptionsForCall(options));
+  async getAllPins(requestOptions) {
+    return pinning.getAllPins(this.getRequestOptionsForCall(requestOptions));
   }
   /**
    * Get pinning status of chunk with given reference
    *
    * @param reference Bee data reference in hex string (either 64 or 128 chars long) or ENS domain.
-   * @param options Options that affects the request behavior
-   * @throws TypeError if some of the input parameters is not expected type
-   * @throws BeeArgumentError if there is passed ENS domain with invalid unicode characters
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Pinning](https://docs.ethswarm.org/docs/develop/access-the-swarm/pinning)
    */
-  async getPin(reference, options) {
+  async getPin(reference, requestOptions) {
     reference = new Reference(reference);
-    return pinning.getPin(this.getRequestOptionsForCall(options), reference);
+    return pinning.getPin(this.getRequestOptionsForCall(requestOptions), reference);
   }
   /**
    * Instructs the Bee node to reupload a locally pinned data into the network.
    *
+   * @param postageBatchId Postage Batch ID that will be used to re-upload the data.
    * @param reference Bee data reference to be re-uploaded in hex string (either 64 or 128 chars long) or ENS domain.
-   * @param options Options that affects the request behavior
-   * @throws BeeArgumentError if the reference is not locally pinned
-   * @throws TypeError if some of the input parameters is not expected type
-   * @throws BeeArgumentError if there is passed ENS domain with invalid unicode characters
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee API reference - `PUT /stewardship`](https://docs.ethswarm.org/api/#tag/Stewardship/paths/~1stewardship~1{reference}/put)
    */
-  async reuploadPinnedData(postageBatchId, reference, options) {
+  async reuploadPinnedData(postageBatchId, reference, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
     reference = new Reference(reference);
-    await stewardship.reupload(this.getRequestOptionsForCall(options), postageBatchId, reference);
+    await stewardship.reupload(this.getRequestOptionsForCall(requestOptions), postageBatchId, reference);
   }
   /**
    * Checks if content specified by reference is retrievable from the network.
    *
    * @param reference Bee data reference to be checked in hex string (either 64 or 128 chars long) or ENS domain.
-   * @param options Options that affects the request behavior
-   * @throws TypeError if some of the input parameters is not expected type
-   * @throws BeeArgumentError if there is passed ENS domain with invalid unicode characters
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee API reference - `GET /stewardship`](https://docs.ethswarm.org/api/#tag/Stewardship/paths/~1stewardship~1{reference}/get)
    */
-  async isReferenceRetrievable(reference, options) {
+  async isReferenceRetrievable(reference, requestOptions) {
     reference = new Reference(reference);
-    return stewardship.isRetrievable(this.getRequestOptionsForCall(options), reference);
+    return stewardship.isRetrievable(this.getRequestOptionsForCall(requestOptions), reference);
   }
   /**
-   * Functions that validates if feed is retrievable in the network.
+   * Functions that validate if feed is retrievable in the network.
    *
    * If no index is passed then it check for "latest" update, which is a weaker guarantee as nobody can be really
    * sure what is the "latest" update.
@@ -536,6 +604,7 @@ export class Bee {
    * @param topic
    * @param index
    * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
   async isFeedRetrievable(owner, topic, index, options, requestOptions) {
     owner = new EthAddress(owner);
@@ -565,35 +634,32 @@ export class Bee {
    * most likely for setting up an encrypted communication
    * channel by sending an one-off message.
    *
-   * **Warning! If the recipient Bee node is a light node, then he will never receive the message!**
-   * This is because light nodes does not fully participate in the data exchange in Swarm network and hence the message won't arrive to them.
+   * **Warning! Only full nodes can accept PSS messages.**
    *
    * @param postageBatchId Postage BatchId that will be assigned to sent message
    * @param topic Topic name
    * @param target Target message address prefix. Has a limit on length. Recommend to use `Utils.Pss.makeMaxTarget()` to get the most specific target that Bee node will accept.
    * @param data Message to be sent
    * @param recipient Recipient public key
-   * @param options Options that affects the request behavior
-   * @throws TypeError if `data`, `batchId`, `target` or `recipient` are in invalid format
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - PSS](https://docs.ethswarm.org/docs/develop/tools-and-features/pss)
    * @see [Bee API reference - `POST /pss`](https://docs.ethswarm.org/api/#tag/Postal-Service-for-Swarm/paths/~1pss~1send~1{topic}~1{targets}/post)
    */
-  async pssSend(postageBatchId, topic, target, data, recipient, options) {
+  async pssSend(postageBatchId, topic, target, data, recipient, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
     assertData(data);
     if (recipient) {
       recipient = new PublicKey(recipient);
-      return pss.send(this.getRequestOptionsForCall(options), topic, target, data, postageBatchId, recipient);
+      return pss.send(this.getRequestOptionsForCall(requestOptions), topic, target, data, postageBatchId, recipient);
     } else {
-      return pss.send(this.getRequestOptionsForCall(options), topic, target, data, postageBatchId);
+      return pss.send(this.getRequestOptionsForCall(requestOptions), topic, target, data, postageBatchId);
     }
   }
   /**
-   * Subscribe to messages for given topic with Postal Service for Swarm
+   * Subscribes to messages for given topic with the Postal Service for Swarm.
    *
-   * **Warning! If connected Bee node is a light node, then he will never receive any message!**
-   * This is because light nodes does not fully participate in the data exchange in Swarm network and hence the message won't arrive to them.
+   * **Warning! Only full nodes can accept PSS messages.**
    *
    * @param topic Topic name
    * @param handler Message handler interface
@@ -608,16 +674,13 @@ export class Bee {
     const ws = pss.subscribe(this.url, topic, this.requestOptions.headers);
     let cancelled = false;
     const cancel = () => {
-      if (cancelled === false) {
+      if (!cancelled) {
         cancelled = true;
-        // although the WebSocket API offers a `close` function, it seems that
-        // with the library that we are using (isomorphic-ws) it doesn't close
-        // the websocket properly, whereas `terminate` does
         if (ws.terminate) {
           ws.terminate();
         } else {
           ws.close();
-        } // standard Websocket in browser does not have terminate function
+        }
       }
     };
     const subscription = {
@@ -631,28 +694,24 @@ export class Bee {
       }
     };
     ws.onerror = event => {
-      // ignore errors after subscription was cancelled
       if (!cancelled) {
         handler.onError(new BeeError(event.message), subscription);
       }
     };
+    ws.onclose = () => {
+      handler.onClose(subscription);
+    };
     return subscription;
   }
   /**
-   * Receive message with Postal Service for Swarm
-   *
-   * Because sending a PSS message is slow and CPU intensive,
-   * it is not supposed to be used for general messaging but
-   * most likely for setting up an encrypted communication
-   * channel by sending an one-off message.
+   * Receives message using the Postal Service for Swarm.
    *
    * This is a helper function to wait for exactly one message to
    * arrive and then cancel the subscription. Additionally a
    * timeout can be provided for the message to arrive or else
    * an error will be thrown.
    *
-   * **Warning! If connected Bee node is a light node, then he will never receive any message!**
-   * This is because light nodes does not fully participate in the data exchange in Swarm network and hence the message won't arrive to them.
+   * **Warning! Only full nodes can accept PSS messages.**
    *
    * @param topic Topic name
    * @param timeoutMsec Timeout in milliseconds
@@ -678,6 +737,10 @@ export class Bee {
           clearTimeout(timeout);
           subscription.cancel();
           resolve(message);
+        },
+        onClose: () => {
+          clearTimeout(timeout);
+          subscription.cancel();
         }
       });
       if (timeoutMsec > 0) {
@@ -688,6 +751,22 @@ export class Bee {
       }
     });
   }
+  /**
+   * Mines the signer (a private key) to be used to send GSOC messages to the specific target overlay address.
+   *
+   * Use {@link gsocSend} to send GSOC messages with the mined signer.
+   *
+   * Use {@link gsocSubscribe} to subscribe to GSOC messages for the specified owner (of the signer) and identifier.
+   *
+   * See {@link gsocSend} or {@link gsocSubscribe} for concrete examples of usage.
+   *
+   * **Warning! Only full nodes can accept GSOC messages.**
+   *
+   * @param targetOverlay
+   * @param identifier
+   * @param proximity
+   * @returns
+   */
   gsocMine(targetOverlay, identifier, proximity = 12) {
     targetOverlay = new PeerAddress(targetOverlay);
     identifier = new Identifier(identifier);
@@ -703,6 +782,29 @@ export class Bee {
     }
     throw Error('Could not mine a valid signer');
   }
+  /**
+   * Sends a GSOC message with the specified signer and identifier.
+   *
+   * Use {@link gsocMine} to mine a signer for the target overlay address.
+   *
+   * Use {@link gsocSubscribe} to subscribe to GSOC messages for the specified owner (of the signer) and identifier.
+   *
+   * **Warning! Only full nodes can accept GSOC messages.**
+   *
+   * @param postageBatchId
+   * @param signer
+   * @param identifier
+   * @param data
+   * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   *
+   * @example
+   * const identifier = NULL_IDENTIFIER
+   * const overlay = '0x1234567890123456789012345678901234567890'
+   * const signer = bee.gsocMine(overlay, identifier)
+   * await bee.gsocSend(postageBatchId, signer, identifier, 'GSOC!')
+   */
   async gsocSend(postageBatchId, signer, identifier, data, options, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
     signer = new PrivateKey(signer);
@@ -711,6 +813,37 @@ export class Bee {
     const soc = makeSingleOwnerChunk(cac, identifier, signer);
     return gsoc.send(this.getRequestOptionsForCall(requestOptions), soc, postageBatchId, options);
   }
+  /**
+   * Subscribes to GSOC messages for the specified owner (of the signer) and identifier.
+   *
+   * Use {@link gsocMine} to mine a signer for the target overlay address.
+   *
+   * Use {@link gsocSend} to send GSOC messages with the mined signer.
+   *
+   * **Warning! Only full nodes can accept GSOC messages.**
+   *
+   * @param address
+   * @param identifier
+   * @param handler
+   * @returns
+   *
+   * @example
+   * const identifier = NULL_IDENTIFIER
+   * const { overlay } = await bee.getNodeAddresses()
+   * const signer = bee.gsocMine(overlay, identifier)
+   *
+   * const subscription = bee.gsocSubscribe(signer.publicKey().address(), identifier, {
+   *   onMessage(message) {
+   *     // handle
+   *   },
+   *   onError(error) {
+   *     // handle
+   *   },
+   *   onClose() {
+   *     // handle
+   *   }
+   * })
+   */
   gsocSubscribe(address, identifier, handler) {
     address = new EthAddress(address);
     identifier = new Identifier(identifier);
@@ -719,7 +852,7 @@ export class Bee {
     const ws = gsoc.subscribe(this.url, socAddress, this.requestOptions.headers);
     let cancelled = false;
     const cancel = () => {
-      if (cancelled === false) {
+      if (!cancelled) {
         cancelled = true;
         if (ws.terminate) {
           ws.terminate();
@@ -743,17 +876,21 @@ export class Bee {
         handler.onError(new BeeError(event.message), subscription);
       }
     };
+    ws.onclose = () => {
+      handler.onClose(subscription);
+    };
     return subscription;
   }
   /**
-   * Create feed manifest chunk and return the reference to it.
+   * Creates a feed manifest chunk and returns the reference to it.
    *
-   * Feed manifest chunk allows for a feed to be able to be resolved through `/bzz` endpoint.
+   * Feed manifest chunks allow for a feed to be able to be resolved through `/bzz` endpoint.
    *
    * @param postageBatchId  Postage BatchId to be used to create the Feed Manifest
    * @param topic           Topic in hex or bytes
    * @param owner           Owner's ethereum address in hex or bytes
    * @param options Options that affects the request behavior
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Feeds](https://docs.ethswarm.org/docs/develop/tools-and-features/feeds)
    * @see [Bee API reference - `POST /feeds`](https://docs.ethswarm.org/api/#tag/Feed/paths/~1feeds~1{owner}~1{topic}/post)
@@ -768,35 +905,35 @@ export class Bee {
     return createFeedManifest(this.getRequestOptionsForCall(requestOptions), owner, topic, postageBatchId, options);
   }
   /**
-   * Make a new feed reader for downloading feed updates.
+   * Makes a new feed reader for downloading feed updates.
    *
    * @param topic   Topic in hex or bytes
    * @param owner   Owner's ethereum address in hex or bytes
-   * @param options Options that affects the request behavior
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Feeds](https://docs.ethswarm.org/docs/develop/tools-and-features/feeds)
    */
-  makeFeedReader(topic, owner, options) {
+  makeFeedReader(topic, owner, requestOptions) {
     topic = new Topic(topic);
     owner = new EthAddress(owner);
-    return makeFeedReader(this.getRequestOptionsForCall(options), topic, owner);
+    return makeFeedReader(this.getRequestOptionsForCall(requestOptions), topic, owner);
   }
   /**
-   * Make a new feed writer for updating feeds
+   * Makes a new feed writer for updating feeds
    *
    * @param topic   Topic in hex or bytes
    * @param signer  The signer's private key or a Signer instance that can sign data
-   * @param options Options that affects the request behavior
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Feeds](https://docs.ethswarm.org/docs/develop/tools-and-features/feeds)
    */
-  makeFeedWriter(topic, signer, options) {
+  makeFeedWriter(topic, signer, requestOptions) {
     topic = new Topic(topic);
     signer = signer ? new PrivateKey(signer) : this.signer;
     if (!signer) {
       throw Error('No signer provided');
     }
-    return makeFeedWriter(this.getRequestOptionsForCall(options), topic, signer);
+    return makeFeedWriter(this.getRequestOptionsForCall(requestOptions), topic, signer);
   }
   async fetchLatestFeedUpdate(topic, owner, requestOptions) {
     topic = new Topic(topic);
@@ -807,62 +944,91 @@ export class Bee {
    * Returns an object for reading single owner chunks
    *
    * @param ownerAddress The ethereum address of the owner
-   * @param options Options that affects the request behavior
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    * @see [Bee docs - Chunk Types](https://docs.ethswarm.org/docs/develop/tools-and-features/chunk-types#single-owner-chunks)
    */
-  makeSOCReader(ownerAddress, options) {
+  makeSOCReader(ownerAddress, requestOptions) {
     ownerAddress = new EthAddress(ownerAddress);
     return {
       owner: ownerAddress,
-      download: downloadSingleOwnerChunk.bind(null, this.getRequestOptionsForCall(options), ownerAddress)
+      download: downloadSingleOwnerChunk.bind(null, this.getRequestOptionsForCall(requestOptions), ownerAddress)
     };
   }
   /**
    * Returns an object for reading and writing single owner chunks
    *
    * @param signer The signer's private key or a Signer instance that can sign data
-   * @param options Options that affects the request behavior
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    * @see [Bee docs - Chunk Types](https://docs.ethswarm.org/docs/develop/tools-and-features/chunk-types#single-owner-chunks)
    */
-  makeSOCWriter(signer, options) {
+  makeSOCWriter(signer, requestOptions) {
     signer = signer ? new PrivateKey(signer) : this.signer;
     if (!signer) {
       throw Error('No signer provided');
     }
     return {
-      ...this.makeSOCReader(signer.publicKey().address(), options),
-      upload: uploadSingleOwnerChunkData.bind(null, this.getRequestOptionsForCall(options), signer)
+      ...this.makeSOCReader(signer.publicKey().address(), requestOptions),
+      upload: uploadSingleOwnerChunkData.bind(null, this.getRequestOptionsForCall(requestOptions), signer)
     };
   }
-  async createEnvelope(postageBatchId, reference, options) {
+  /**
+   * Creates the postage batch signature for a specific chunk address.
+   *
+   * This is for advanced usage, where a pre-signed chunk can be uploaded
+   * through a different Bee node.
+   *
+   * @param postageBatchId
+   * @param reference
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
+   * @example
+   * const envelope = await bee.createEnvelope(batchId, chunk.address)
+   * await bee.uploadChunk(envelope, chunk)
+   *
+   * @returns
+   */
+  async createEnvelope(postageBatchId, reference, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
     reference = new Reference(reference);
-    return postEnvelope(this.getRequestOptionsForCall(options), postageBatchId, reference);
+    return postEnvelope(this.getRequestOptionsForCall(requestOptions), postageBatchId, reference);
   }
   /**
-   * Get reserve commitment hash duration seconds
+   * Gets reserve commitment hash duration seconds.
+   *
+   * To be able to participe in the storage incentives and not get frozen, this should
+   * ideally run under 5 minutes.
+   *
+   * This is a CPU intensice operation, as roughly 2^22 chunks are hashed in the process.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
+   * @example
+   * const addresses = await bee.getNodeAddresses()
+   * const topology = await bee.getTopology()
+   * const result = await bee.rchash(topology.depth, addresses.overlay.toHex(), addresses.overlay.toHex())
+   * // result is a number of seconds
    */
-  async rchash(depth, anchor1, anchor2, options) {
-    return rchash(this.getRequestOptionsForCall(options), depth, anchor1, anchor2);
+  async rchash(depth, anchor1, anchor2, requestOptions) {
+    return rchash(this.getRequestOptionsForCall(requestOptions), depth, anchor1, anchor2);
   }
   /**
-   * Ping the Bee node to see if there is a live Bee node on the given URL.
+   * Pings the Bee node to see if there is a live Bee node on the given URL.
    *
-   * @param options Options that affects the request behavior
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    * @throws If connection was not successful throw error
    */
-  async checkConnection(options) {
-    return status.checkConnection(this.getRequestOptionsForCall(options));
+  async checkConnection(requestOptions) {
+    return status.checkConnection(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Ping the Bee node to see if there is a live Bee node on the given URL.
+   * Pings the Bee node to see if there is a live Bee node on the given URL.
    *
-   * @param options Options that affects the request behavior
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    * @returns true if successful, false on error
    */
-  async isConnected(options) {
+  async isConnected(requestOptions) {
     try {
-      await status.checkConnection(this.getRequestOptionsForCall(options));
+      await status.checkConnection(this.getRequestOptionsForCall(requestOptions));
     } catch (e) {
       return false;
     }
@@ -874,117 +1040,170 @@ export class Bee {
    * Do note that this is not a standard way to check for gateway nodes,
    * but some of the gateway tooling expose this endpoint.
    *
-   * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async isGateway(options) {
-    return status.isGateway(this.getRequestOptionsForCall(options));
+  async isGateway(requestOptions) {
+    return status.isGateway(this.getRequestOptionsForCall(requestOptions));
   }
-  // Legacy debug API
-  async getNodeAddresses(options) {
-    return connectivity.getNodeAddresses(this.getRequestOptionsForCall(options));
+  /**
+   * Fetches the overlay, underlay, Ethereum, and other addresses of the Bee node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
+  async getNodeAddresses(requestOptions) {
+    return connectivity.getNodeAddresses(this.getRequestOptionsForCall(requestOptions));
   }
-  async getBlocklist(options) {
-    return connectivity.getBlocklist(this.getRequestOptionsForCall(options));
+  /**
+   * Fetches the list of blocked peers for this node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
+  async getBlocklist(requestOptions) {
+    return connectivity.getBlocklist(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get list of peers for this node
+   * Gets list of peers for this node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getPeers(options) {
-    return connectivity.getPeers(this.getRequestOptionsForCall(options));
+  async getPeers(requestOptions) {
+    return connectivity.getPeers(this.getRequestOptionsForCall(requestOptions));
   }
-  async removePeer(peer, options) {
+  /**
+   * Disconnects from a specific peer.
+   *
+   * @param peer Overlay address of the peer to be removed.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
+  async removePeer(peer, requestOptions) {
     peer = new PeerAddress(peer);
-    return connectivity.removePeer(this.getRequestOptionsForCall(options), peer);
+    return connectivity.removePeer(this.getRequestOptionsForCall(requestOptions), peer);
   }
-  async getTopology(options) {
-    return connectivity.getTopology(this.getRequestOptionsForCall(options));
+  /**
+   * Fetches topology and connectivity information of the Bee node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
+  async getTopology(requestOptions) {
+    return connectivity.getTopology(this.getRequestOptionsForCall(requestOptions));
   }
-  async pingPeer(peer, options) {
+  /**
+   * Pings a specific peer to check its availability.
+   *
+   * @param peer Overlay address of the peer to be pinged.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
+  async pingPeer(peer, requestOptions) {
     peer = new PeerAddress(peer);
-    return connectivity.pingPeer(this.getRequestOptionsForCall(options), peer);
+    return connectivity.pingPeer(this.getRequestOptionsForCall(requestOptions), peer);
   }
-  /*
-   * Balance endpoints
-   */
   /**
-   * Get the balances with all known peers including prepaid services
+   * Gets the SWAP balances with all known peers including prepaid services.
+   *
+   * This is related to the bandwidth incentives and the chequebook.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getAllBalances(options) {
-    return balance.getAllBalances(this.getRequestOptionsForCall(options));
+  async getAllBalances(requestOptions) {
+    return balance.getAllBalances(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get the balances with a specific peer including prepaid services
+   * Gets the SWAP balances for a specific peer including prepaid services.
    *
    * @param address Swarm address of peer
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getPeerBalance(address, options) {
+  async getPeerBalance(address, requestOptions) {
     address = new PeerAddress(address);
-    return balance.getPeerBalance(this.getRequestOptionsForCall(options), address);
+    return balance.getPeerBalance(this.getRequestOptionsForCall(requestOptions), address);
   }
   /**
-   * Get the past due consumption balances with all known peers
+   * Gets the past due consumption balances for all known peers.
+   *
+   * This is related to the bandwidth incentives and the chequebook.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getPastDueConsumptionBalances(options) {
-    return balance.getPastDueConsumptionBalances(this.getRequestOptionsForCall(options));
+  async getPastDueConsumptionBalances(requestOptions) {
+    return balance.getPastDueConsumptionBalances(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get the past due consumption balance with a specific peer
+   * Gets the past due consumption balance for a specific peer.
+   *
+   * This is related to the bandwidth incentives and the chequebook.
    *
    * @param address Swarm address of peer
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getPastDueConsumptionPeerBalance(address, options) {
+  async getPastDueConsumptionPeerBalance(address, requestOptions) {
     address = new PeerAddress(address);
-    return balance.getPastDueConsumptionPeerBalance(this.getRequestOptionsForCall(options), address);
+    return balance.getPastDueConsumptionPeerBalance(this.getRequestOptionsForCall(requestOptions), address);
   }
-  /*
-   * Chequebook endpoints
-   */
   /**
-   * Get the address of the chequebook contract used.
+   * Gets the address of the deloyed chequebook.
    *
-   * **Warning:** The address is returned with 0x prefix unlike all other calls.
-   * https://github.com/ethersphere/bee/issues/1443
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getChequebookAddress(options) {
-    return chequebook.getChequebookAddress(this.getRequestOptionsForCall(options));
+  async getChequebookAddress(requestOptions) {
+    return chequebook.getChequebookAddress(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get the balance of the chequebook
+   * Gets the balance of the chequebook.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getChequebookBalance(options) {
-    return chequebook.getChequebookBalance(this.getRequestOptionsForCall(options));
+  async getChequebookBalance(requestOptions) {
+    return chequebook.getChequebookBalance(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get last cheques for all peers
+   * Gets the last cheques for all peers.
+   *
+   * This is related to the bandwidth incentives and the chequebook.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getLastCheques(options) {
-    return chequebook.getLastCheques(this.getRequestOptionsForCall(options));
+  async getLastCheques(requestOptions) {
+    return chequebook.getLastCheques(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get last cheques for the peer
+   * Gets the last cheques for a specific peer.
    *
-   * @param address  Swarm address of peer
+   * This is related to the bandwidth incentives and the chequebook.
+   *
+   * @param address Overlay address of peer.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getLastChequesForPeer(address, options) {
+  async getLastChequesForPeer(address, requestOptions) {
     address = new PeerAddress(address);
-    return chequebook.getLastChequesForPeer(this.getRequestOptionsForCall(options), address);
+    return chequebook.getLastChequesForPeer(this.getRequestOptionsForCall(requestOptions), address);
   }
   /**
-   * Get last cashout action for the peer
+   * Gets the last cashout action for a specific peer.
    *
-   * @param address  Swarm address of peer
+   * This is related to the bandwidth incentives and the chequebook.
+   *
+   * @param address Overlay address of peer.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getLastCashoutAction(address, options) {
+  async getLastCashoutAction(address, requestOptions) {
     address = new PeerAddress(address);
-    return chequebook.getLastCashoutAction(this.getRequestOptionsForCall(options), address);
+    return chequebook.getLastCashoutAction(this.getRequestOptionsForCall(requestOptions), address);
   }
   /**
-   * Cashout the last cheque for the peer
+   * Cashes out the last cheque for a specific peer.
+   *
+   * This is related to the bandwidth incentives and the chequebook.
    *
    * @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
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
   async cashoutLastCheque(address, options, requestOptions) {
     address = new PeerAddress(address);
@@ -994,24 +1213,28 @@ export class Bee {
     return chequebook.cashoutLastCheque(this.getRequestOptionsForCall(requestOptions), address, options);
   }
   /**
-   * Deposit tokens from node wallet into chequebook
+   * Deposits tokens from the node wallet into the chequebook.
    *
    * @param amount  Amount of tokens to deposit (must be positive integer)
    * @param gasPrice Gas Price in WEI for the transaction call
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
    * @return string  Hash of the transaction
    * @deprecated Use `depositBZZToChequebook` instead.
    */
-  async depositTokens(amount, gasPrice, options) {
-    return this.depositBZZToChequebook(amount, gasPrice, options);
+  async depositTokens(amount, gasPrice, requestOptions) {
+    return this.depositBZZToChequebook(amount, gasPrice, requestOptions);
   }
   /**
-   * Deposit tokens from node wallet into chequebook
+   * Deposits tokens from the node wallet into the chequebook.
    *
    * @param amount  Amount of tokens to deposit (must be positive integer)
    * @param gasPrice Gas Price in WEI for the transaction call
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
    * @return string  Hash of the transaction
    */
-  async depositBZZToChequebook(amount, gasPrice, options) {
+  async depositBZZToChequebook(amount, gasPrice, requestOptions) {
     const amountString = amount instanceof BZZ ? amount.toPLURString() : asNumberString(amount, {
       min: 1n,
       name: 'amount'
@@ -1023,27 +1246,29 @@ export class Bee {
         name: 'gasPrice'
       });
     }
-    return chequebook.depositTokens(this.getRequestOptionsForCall(options), amountString, gasPriceString);
+    return chequebook.depositTokens(this.getRequestOptionsForCall(requestOptions), amountString, gasPriceString);
   }
   /**
-   * Withdraw tokens from the chequebook to the node wallet
+   * Withdraws tokens from the chequebook to the node wallet.
    *
    * @param amount  Amount of tokens to withdraw (must be positive integer)
    * @param gasPrice Gas Price in WEI for the transaction call
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
    * @return string  Hash of the transaction
    * @deprecated Use `withdrawBZZFromChequebook` instead.
    */
-  async withdrawTokens(amount, gasPrice, options) {
-    return this.withdrawBZZFromChequebook(amount, gasPrice, options);
+  async withdrawTokens(amount, gasPrice, requestOptions) {
+    return this.withdrawBZZFromChequebook(amount, gasPrice, requestOptions);
   }
   /**
-   * Withdraw tokens from the chequebook to the node wallet
+   * Withdraws tokens from the chequebook to the node wallet.
    *
-   * @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
+   * @param amount Amount of BZZ tokens to withdraw. If not providing a `BZZ` instance, the amount is denoted in PLUR.
+   * @param gasPrice Gas Price in WEI for the transaction call.
+   * @return Transaction ID
    */
-  async withdrawBZZFromChequebook(amount, gasPrice, options) {
+  async withdrawBZZFromChequebook(amount, gasPrice, requestOptions) {
     // TODO: check BZZ in tests
     const amountString = amount instanceof BZZ ? amount.toPLURString() : asNumberString(amount, {
       min: 1n,
@@ -1056,67 +1281,95 @@ export class Bee {
         name: 'gasPrice'
       });
     }
-    return chequebook.withdrawTokens(this.getRequestOptionsForCall(options), amountString, gasPriceString);
+    return chequebook.withdrawTokens(this.getRequestOptionsForCall(requestOptions), amountString, gasPriceString);
   }
-  async withdrawBZZToExternalWallet(amount, address, options) {
+  /**
+   * Withdraws BZZ from the node wallet (not chequebook) to a whitelisted external wallet address.
+   *
+   * @param amount Amount of BZZ tokens to withdraw. If not providing a `BZZ` instance, the amount is denoted in PLUR.
+   * @param address
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @return Transaction ID
+   */
+  async withdrawBZZToExternalWallet(amount, address, requestOptions) {
     amount = amount instanceof BZZ ? amount : BZZ.fromPLUR(amount);
     address = new EthAddress(address);
-    return states.withdrawBZZ(this.getRequestOptionsForCall(options), amount, address);
+    return states.withdrawBZZ(this.getRequestOptionsForCall(requestOptions), amount, address);
   }
-  async withdrawDAIToExternalWallet(amount, address, options) {
+  /**
+   * Withdraws DAI from the node wallet (not chequebook) to a whitelisted external wallet address.
+   *
+   * @param amount Amount of DAI tokens to withdraw. If not providing a `DAI` instance, the amount is denoted in wei.
+   * @param address
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @return Transaction ID
+   */
+  async withdrawDAIToExternalWallet(amount, address, requestOptions) {
     amount = amount instanceof DAI ? amount : DAI.fromWei(amount);
     address = new EthAddress(address);
-    return states.withdrawDAI(this.getRequestOptionsForCall(options), amount, address);
+    return states.withdrawDAI(this.getRequestOptionsForCall(requestOptions), amount, address);
   }
-  /*
-   * Settlements endpoint
-   */
   /**
-   * Get amount of sent and received from settlements with a peer
+   * Gets the amount of sent and received micropayments from settlements with a peer.
+   *
+   * This is related to the bandwidth incentives and the chequebook.
    *
    * @param address  Swarm address of peer
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getSettlements(address, options) {
+  async getSettlements(address, requestOptions) {
     address = new PeerAddress(address);
-    return settlements.getSettlements(this.getRequestOptionsForCall(options), address);
+    return settlements.getSettlements(this.getRequestOptionsForCall(requestOptions), address);
   }
   /**
-   * Get settlements with all known peers and total amount sent or received
+   * Gets settlements with all known peers and total amount sent or received.
+   *
+   * This is related to the bandwidth incentives and the chequebook.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getAllSettlements(options) {
-    return settlements.getAllSettlements(this.getRequestOptionsForCall(options));
+  async getAllSettlements(requestOptions) {
+    return settlements.getAllSettlements(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get status of node
+   * Gets the general status of the node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getStatus(options) {
-    return debugStatus.getDebugStatus(this.getRequestOptionsForCall(options));
+  async getStatus(requestOptions) {
+    return debugStatus.getDebugStatus(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get health of node
+   * Gets the health of the node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getHealth(options) {
-    return debugStatus.getHealth(this.getRequestOptionsForCall(options));
+  async getHealth(requestOptions) {
+    return debugStatus.getHealth(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get readiness of node
+   * Gets the readiness status of the node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getReadiness(options) {
-    return debugStatus.getReadiness(this.getRequestOptionsForCall(options));
+  async getReadiness(requestOptions) {
+    return debugStatus.getReadiness(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get mode information of node
+   * Get mode information of node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getNodeInfo(options) {
-    return debugStatus.getNodeInfo(this.getRequestOptionsForCall(options));
+  async getNodeInfo(requestOptions) {
+    return debugStatus.getNodeInfo(this.getRequestOptionsForCall(requestOptions));
   }
   /**
    * Connects to a node and checks if its version matches with the one that bee-js supports.
    *
-   * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async isSupportedExactVersion(options) {
-    return debugStatus.isSupportedExactVersion(this.getRequestOptionsForCall(options));
+  async isSupportedExactVersion(requestOptions) {
+    return debugStatus.isSupportedExactVersion(this.getRequestOptionsForCall(requestOptions));
   }
   /**
    *
@@ -1124,53 +1377,56 @@ export class Bee {
    *
    * This should be the main way how to check compatibility for your app and Bee node.
    *
-   * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async isSupportedApiVersion(options) {
-    return debugStatus.isSupportedApiVersion(this.getRequestOptionsForCall(options));
+  async isSupportedApiVersion(requestOptions) {
+    return debugStatus.isSupportedApiVersion(this.getRequestOptionsForCall(requestOptions));
   }
   /**
    * 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
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getVersions(options) {
-    return debugStatus.getVersions(this.getRequestOptionsForCall(options));
+  async getVersions(requestOptions) {
+    return debugStatus.getVersions(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get reserve state
+   * Get reserve state.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getReserveState(options) {
-    return states.getReserveState(this.getRequestOptionsForCall(options));
+  async getReserveState(requestOptions) {
+    return states.getReserveState(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get chain state
+   * Gets chain state.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getChainState(options) {
-    return states.getChainState(this.getRequestOptionsForCall(options));
+  async getChainState(requestOptions) {
+    return states.getChainState(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Get wallet balances for DAI and BZZ of the Bee node
+   * Gets DAI and BZZ balances of the Bee node wallet.
    *
-   * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getWalletBalance(options) {
-    return states.getWalletBalance(this.getRequestOptionsForCall(options));
+  async getWalletBalance(requestOptions) {
+    return states.getWalletBalance(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Creates new postage batch from the funds that the node has available in its Ethereum account.
+   * Creates a new postage batch, spending BZZ tokens from the node wallet.
    *
-   * 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/develop/access-the-swarm/introduction#keep-your-data-alive).
+   * Use {@link buyStorage} for a more convenient way to create postage batch.
    *
-   * **WARNING: THIS CREATES TRANSACTIONS THAT SPENDS MONEY**
+   * For better understanding what each parameter means and what the optimal values are, see
+   * [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction#keep-your-data-alive).
    *
-   * @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 amount TTL parameter - 1 day at the minimum of 24,000 storage price requires an amount of 414,720,000.
+   * @param depth Capacity parameter - 17..255 - depth 17 provides 512MB of theoretical capacity, 18 provides 1GB, 19 provides 2GB, etc.
    * @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
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee Debug API reference - `POST /stamps`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps~1{amount}~1{depth}/post)
@@ -1197,193 +1453,388 @@ export class Bee {
     }
     return stamp;
   }
-  async buyStorage(size, duration, options, requestOptions) {
+  /**
+   * A more convenient method to create a postage batch, which is analogous
+   * to buying storage for a certain size and duration on the Swarm network.
+   *
+   * Use {@link getStorageCost} to calculate the cost of creating a postage batch.
+   *
+   * For the low level API, use {@link createPostageBatch}.
+   *
+   * @example const batchId = await bee.buyStorage(Size.fromGigabytes(8), Duration.fromDays(31))
+      * @param size
+   * @param duration
+   * @param options
+   * @param requestOptions
+   * @param encryption
+   * @param erasureCodeLevel
+   * @returns
+   */
+  async buyStorage(size, duration, options, requestOptions, encryption, erasureCodeLevel) {
     const chainState = await this.getChainState(requestOptions);
     const amount = getAmountForDuration(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
-    const depth = getDepthForSize(size);
+    const depth = getDepthForSize(size, encryption, erasureCodeLevel);
     if (options) {
       options = preparePostageBatchOptions(options);
     }
     return this.createPostageBatch(amount, depth, options, requestOptions);
   }
-  async getStorageCost(size, duration, options) {
-    const chainState = await this.getChainState(options);
+  /**
+   * Calculates the estimated BZZ cost for creating a postage batch for the given size and duration.
+   *
+   * Use {@link buyStorage} to create a postage batch with the calculated cost.
+   *
+   * @example const bzz = await bee.getStorageCost(Size.fromGigabytes(1), Duration.fromDays(30))
+   *
+   * @param size Size of the data to be stored.
+   * @param duration Duration for which the data should be stored.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @param encryption Assume the future uploaded data is encrypted, which skews the capacity of the postage batch.
+   * @param erasureCodeLevel Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch.
+   * @returns
+   */
+  async getStorageCost(size, duration, requestOptions, encryption, erasureCodeLevel) {
+    const chainState = await this.getChainState(requestOptions);
     const amount = getAmountForDuration(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
-    const depth = getDepthForSize(size);
+    const depth = getDepthForSize(size, encryption, erasureCodeLevel);
     return getStampCost(depth, amount);
   }
-  async extendStorageSize(postageBatchId, size, options) {
-    const batch = await this.getPostageBatch(postageBatchId, options);
-    const depth = getDepthForSize(size);
+  /**
+   * Extends the storage of a postage batch by either increasing its size, duration or both.
+   *
+   * The size is ABSOLUTE, while the duration is RELATIVE to the current duration of the postage batch.
+   *
+   * Use {@link getExtensionCost} to calculate the cost of extending the storage.
+   *
+   * @example
+   * // Increases the size to 8GB (unless it is already at 8GB or higher)
+   * // and extends the duration by 30 days (regardless of the current duration).
+   * await bee.extendStorage(batchId, Size.fromGigabytes(8), Duration.fromDays(30))
+   *
+   * @example
+   * // To increase the duration to a desired date, pass a second parameter to `Duration.fromEndDate`.
+   * // With the second parameter, the duration is set to the difference between the current end date and the desired end date.
+   * const oneMonth = new Date(Date.now() + Dates.days(31))
+   * const batch = await bee.getPostageBatch(batchId)
+   * await bee.extendStorage(batchId, Size.fromGigabytes(8), Duration.fromEndDate(oneMonth, batch.duration.toEndDate()))
+   *
+   * @param postageBatchId Batch ID of the postage batch to extend.
+   * @param size Absolute size to extend the postage batch to.
+   * @param duration Relative duration to extend the postage batch by.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @param encryption Assume the future uploaded data is encrypted, which skews the capacity of the postage batch.
+   * @param erasureCodeLevel Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch.
+   * @returns
+   */
+  async extendStorage(postageBatchId, size, duration, requestOptions, encryption, erasureCodeLevel) {
+    const batch = await this.getPostageBatch(postageBatchId, requestOptions);
+    const depth = getDepthForSize(size, encryption, erasureCodeLevel);
+    const chainState = await this.getChainState(requestOptions);
+    const depthDelta = depth - batch.depth;
+    const multiplier = depthDelta <= 0 ? 1n : 2n ** BigInt(depthDelta);
+    const blockTime = this.network === 'gnosis' ? 5 : 15;
+    const additionalAmount = getAmountForDuration(duration, chainState.currentPrice, blockTime);
+    const currentAmount = getAmountForDuration(batch.duration, chainState.currentPrice, blockTime);
+    const targetAmount = duration.isZero() ? currentAmount * multiplier : currentAmount + additionalAmount * multiplier;
+    const amountDelta = targetAmount - currentAmount;
+    const transactionId = await this.topUpBatch(batch.batchID, amountDelta, requestOptions);
+    if (depthDelta > 0) {
+      return this.diluteBatch(batch.batchID, depth, requestOptions);
+    }
+    return transactionId;
+  }
+  /**
+   * Extends the storage size of a postage batch by increasing its depth.
+   *
+   * Use {@link getSizeExtensionCost} to calculate the cost of extending the size.
+   * Use {@link extendStorage} to extend both size and duration.
+   *
+   * @param postageBatchId
+   * @param size Absolute size to extend the postage batch to.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @param encryption Assume the future uploaded data is encrypted, which skews the capacity of the postage batch.
+   * @param erasureCodeLevel Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch.
+   * @returns
+   */
+  async extendStorageSize(postageBatchId, size, requestOptions, encryption, erasureCodeLevel) {
+    const chainState = await this.getChainState(requestOptions);
+    const batch = await this.getPostageBatch(postageBatchId, requestOptions);
+    const depth = getDepthForSize(size, encryption, erasureCodeLevel);
     const delta = depth - batch.depth;
     if (delta <= 0) {
       throw new BeeArgumentError('New depth has to be greater than the original depth', depth);
     }
-    await this.topUpBatch(batch.batchID, BigInt(batch.amount) * 2n ** BigInt(delta - 1) + 1n, options);
-    return this.diluteBatch(batch.batchID, depth, options);
+    const currentAmount = getAmountForDuration(batch.duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
+    await this.topUpBatch(batch.batchID, currentAmount * (2n ** BigInt(delta) - 1n) + 1n, requestOptions);
+    return this.diluteBatch(batch.batchID, depth, requestOptions);
   }
-  async extendStorageDuration(postageBatchId, duration, options) {
-    const batch = await this.getPostageBatch(postageBatchId, options);
-    const chainState = await this.getChainState(options);
+  /**
+   * Extends the duration of a postage batch.
+   *
+   * Use {@link getDurationExtensionCost} to calculate the cost of extending the duration.
+   * Use {@link extendStorage} to extend both size and duration.
+   *
+   * @param postageBatchId
+   * @param duration Relative duration to extend the postage batch by.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
+  async extendStorageDuration(postageBatchId, duration, requestOptions) {
+    const batch = await this.getPostageBatch(postageBatchId, requestOptions);
+    const chainState = await this.getChainState(requestOptions);
     const amount = getAmountForDuration(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
-    return this.topUpBatch(batch.batchID, amount, options);
+    return this.topUpBatch(batch.batchID, amount, requestOptions);
   }
-  async getExtensionCost(postageBatchId, size, duration, options) {
-    const batch = await this.getPostageBatch(postageBatchId, options);
-    const chainState = await this.getChainState(options);
-    const amount = getAmountForDuration(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
-    const depth = getDepthForSize(size);
-    const currentValue = getStampCost(batch.depth, batch.amount);
-    const newValue = getStampCost(depth, amount);
-    return newValue.minus(currentValue);
-  }
-  async getSizeExtensionCost(postageBatchId, size, options) {
-    const batch = await this.getPostageBatch(postageBatchId, options);
-    const depth = getDepthForSize(size);
+  /**
+   * Calculates the cost of extending both the duration and the capacity of a postage batch.
+   *
+   * The size is ABSOLUTE, while the duration is RELATIVE to the current duration of the postage batch.
+   *
+   * Use {@link extendStorage} to extend the the duration and capacity of a postage batch.
+   *
+   * @param postageBatchId
+   * @param size Absolute size to extend the postage batch to.
+   * @param duration Relative duration to extend the postage batch by.
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @param encryption Assume the future uploaded data is encrypted, which skews the capacity of the postage batch.
+   * @param erasureCodeLevel Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch.
+   * @returns
+   */
+  async getExtensionCost(postageBatchId, size, duration, requestOptions, encryption, erasureCodeLevel) {
+    const batch = await this.getPostageBatch(postageBatchId, requestOptions);
+    const chainState = await this.getChainState(requestOptions);
+    const blockTime = this.network === 'gnosis' ? 5 : 15;
+    const amount = duration.isZero() ? 0n : getAmountForDuration(duration, chainState.currentPrice, blockTime);
+    const depth = getDepthForSize(size, encryption, erasureCodeLevel);
+    const currentAmount = getAmountForDuration(batch.duration, chainState.currentPrice, blockTime);
+    const currentCost = getStampCost(batch.depth, currentAmount);
+    const newCost = getStampCost(depth, currentAmount + amount);
+    return newCost.minus(currentCost);
+  }
+  /**
+   * Calculates the cost of extending the size of a postage batch.
+   *
+   * The size is ABSOLUTE, so if the postage batch already equals or is greater than the given size,
+   * the cost will be zero.
+   *
+   * Use {@link extendStorageSize} to extend the size of a postage batch.
+   *
+   * Use {@link getExtensionCost} to get the cost of extending both size and duration.
+   * Use {@link getDurationExtensionCost} to get the cost of extending only the duration.
+   *
+   * @param postageBatchId
+   * @param size
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @param encryption Assume the future uploaded data is encrypted, which skews the capacity of the postage batch.
+   * @param erasureCodeLevel Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch.
+   * @returns
+   */
+  async getSizeExtensionCost(postageBatchId, size, requestOptions, encryption, erasureCodeLevel) {
+    const batch = await this.getPostageBatch(postageBatchId, requestOptions);
+    const chainState = await this.getChainState(requestOptions);
+    const depth = getDepthForSize(size, encryption, erasureCodeLevel);
     const delta = depth - batch.depth;
     if (delta <= 0) {
       throw new BeeArgumentError('New depth has to be greater than the original depth', depth);
     }
-    const currentPaid = getStampCost(batch.depth, batch.amount);
-    const newPaid = getStampCost(depth, batch.amount);
-    return newPaid.minus(currentPaid);
+    const currentAmount = getAmountForDuration(batch.duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
+    const currentCost = getStampCost(batch.depth, currentAmount);
+    const newCost = getStampCost(depth, currentAmount);
+    return newCost.minus(currentCost);
   }
-  async getDurationExtensionCost(postageBatchId, duration, options) {
-    const batch = await this.getPostageBatch(postageBatchId, options);
-    const chainState = await this.getChainState(options);
+  /**
+   * Calculates the cost of extending the duration of a postage batch.
+   *
+   * The duration is RELATIVE to the current duration of the postage batch,
+   * e.g. specifying `Duration.fromDays(30)` will extend the current duration by 30 days,
+   * regardless of the current duration.
+   *
+   * Use {@link extendStorageDuration} to extend the duration of a postage batch.
+   *
+   * Use {@link getExtensionCost} to get the cost of extending both size and duration.
+   * Use {@link getSizeExtensionCost} to get the cost of extending only the size.
+   *
+   * @param postageBatchId
+   * @param duration
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @returns
+   */
+  async getDurationExtensionCost(postageBatchId, duration, requestOptions) {
+    const batch = await this.getPostageBatch(postageBatchId, requestOptions);
+    const chainState = await this.getChainState(requestOptions);
     const amount = getAmountForDuration(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
     return getStampCost(batch.depth, amount);
   }
   /**
-   * Topup a fresh amount of BZZ to given Postage Batch.
+   * Increases the duration of a postage batch by increasing its amount.
+   *
+   * For a more convenient way to extend the postage batch, refer to the methods below.
+   *
+   * Use {@link getDurationExtensionCost}, {@link getSizeExtensionCost} or {@link getExtensionCost}
+   * to calculate the costs of extending the postage batch properties.
+   *
+   * Use {@link extendStorageDuration}, {@link extendStorageSize} or {@link extendStorage}
+   * to extend the postage batch properties.
    *
    * 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/develop/access-the-swarm/introduction/#keep-your-data-alive).
    *
    * @param postageBatchId Batch ID
    * @param amount Amount to be added to the batch
-   * @param options Request options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee Debug API reference - `PATCH /stamps/topup/${id}/${amount}`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps~1topup~1{batch_id}~1{amount}/patch)
    */
-  async topUpBatch(postageBatchId, amount, options) {
+  async topUpBatch(postageBatchId, amount, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
     const amountString = asNumberString(amount, {
       min: 1n,
       name: 'amount'
     });
-    return stamps.topUpBatch(this.getRequestOptionsForCall(options), postageBatchId, amountString);
+    return stamps.topUpBatch(this.getRequestOptionsForCall(requestOptions), postageBatchId, amountString);
   }
   /**
-   * 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.
+   * Dilutes a postage batch to extend its capacity by increasing its depth.
+   *
+   * This is a free operation, as for every depth increase, the capacity is doubled,
+   * but the amount (duration) is halved.
+   *
+   * To increase the capacity of the postage batch while retaining the same amount (duration),
+   * you need to top up the postage batch first using {@link topUpBatch}.
+   *
+   * For a more convenient way to extend the postage batch, refer to the methods below.
+   *
+   * Use {@link getDurationExtensionCost}, {@link getSizeExtensionCost} or {@link getExtensionCost}
+   * to calculate the costs of extending the postage batch properties.
+   *
+   * Use {@link extendStorageDuration}, {@link extendStorageSize} or {@link extendStorage}
+   * to extend the postage batch properties.
    *
    * 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/develop/access-the-swarm/introduction/#keep-your-data-alive).
    *
    * @param postageBatchId Batch ID
    * @param depth Amount to be added to the batch
-   * @param options Request options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee Debug API reference - `PATCH /stamps/topup/${id}/${amount}`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps~1dilute~1%7Bbatch_id%7D~1%7Bdepth%7D/patch)
    */
-  async diluteBatch(postageBatchId, depth, options) {
+  async diluteBatch(postageBatchId, depth, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
     depth = Types.asNumber(depth, {
       name: 'depth',
       min: 18,
       max: 255
     });
-    return stamps.diluteBatch(this.getRequestOptionsForCall(options), postageBatchId, depth);
+    return stamps.diluteBatch(this.getRequestOptionsForCall(requestOptions), postageBatchId, depth);
   }
   /**
-   * Return details for specific postage batch.
+   * Returns details for specific postage batch.
    *
    * @param postageBatchId Batch ID
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee Debug API reference - `GET /stamps/${id}`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps~1%7Bbatch_id%7D/get)
    */
-  async getPostageBatch(postageBatchId, options) {
+  async getPostageBatch(postageBatchId, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
-    return stamps.getPostageBatch(this.getRequestOptionsForCall(options), postageBatchId);
+    return stamps.getPostageBatch(this.getRequestOptionsForCall(requestOptions), postageBatchId);
   }
   /**
    * Return detailed information related to buckets for specific postage batch.
    *
    * @param postageBatchId Batch ID
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee Debug API reference - `GET /stamps/${id}/buckets`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps~1%7Bbatch_id%7D~1buckets/get)
    */
-  async getPostageBatchBuckets(postageBatchId, options) {
+  async getPostageBatchBuckets(postageBatchId, requestOptions) {
     postageBatchId = new BatchId(postageBatchId);
-    return stamps.getPostageBatchBuckets(this.getRequestOptionsForCall(options), postageBatchId);
+    return stamps.getPostageBatchBuckets(this.getRequestOptionsForCall(requestOptions), postageBatchId);
   }
   /**
-   * Return all postage batches that has the node available.
+   * Returns all postage batches that belongs to the node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee Debug API reference - `GET /stamps`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps/get)
    * @deprecated Use `getPostageBatches` instead
    */
-  async getAllPostageBatch(options) {
-    return stamps.getAllPostageBatches(this.getRequestOptionsForCall(options)); // TODO: remove in June 2025
+  async getAllPostageBatch(requestOptions) {
+    return stamps.getAllPostageBatches(this.getRequestOptionsForCall(requestOptions)); // TODO: remove in June 2025
   }
   /**
-   * Return all globally available postage batches.
+   * Returns all postage batches that are globally available on the Swarm network.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
    * @deprecated Use `getGlobalPostageBatches` instead
    */
-  async getAllGlobalPostageBatch(options) {
-    return stamps.getGlobalPostageBatches(this.getRequestOptionsForCall(options)); // TODO: remove in June 2025
+  async getAllGlobalPostageBatch(requestOptions) {
+    return stamps.getGlobalPostageBatches(this.getRequestOptionsForCall(requestOptions)); // TODO: remove in June 2025
   }
   /**
-   * Return all postage batches that belong to the node.
+   * Returns all postage batches that belong to the node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee Debug API reference - `GET /stamps`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps/get)
    */
-  async getPostageBatches(options) {
-    return stamps.getAllPostageBatches(this.getRequestOptionsForCall(options));
+  async getPostageBatches(requestOptions) {
+    return stamps.getAllPostageBatches(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Return all globally available postage batches.
+   * Returns all globally available postage batches.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getGlobalPostageBatches(options) {
-    return stamps.getGlobalPostageBatches(this.getRequestOptionsForCall(options));
+  async getGlobalPostageBatches(requestOptions) {
+    return stamps.getGlobalPostageBatches(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Return lists of all current pending transactions that the Bee made
+   * Fetches the list of all current pending transactions for the Bee node.
+   *
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getAllPendingTransactions(options) {
-    return transactions.getAllTransactions(this.getRequestOptionsForCall(options));
+  async getAllPendingTransactions(requestOptions) {
+    return transactions.getAllTransactions(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Return transaction information for specific transaction
+   * Fetches the transaction information for a specific transaction.
+   *
    * @param transactionHash
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getPendingTransaction(transactionHash, options) {
+  async getPendingTransaction(transactionHash, requestOptions) {
     transactionHash = new TransactionId(transactionHash);
-    return transactions.getTransaction(this.getRequestOptionsForCall(options), transactionHash);
+    return transactions.getTransaction(this.getRequestOptionsForCall(requestOptions), transactionHash);
   }
   /**
-   * Rebroadcast already created transaction.
-   * This is mainly needed when your transaction fall off mempool from other reason is not incorporated into block.
+   * Rebroadcasts already created transaction.
+   *
+   * This is mainly needed when the transaction falls off mempool or is not incorporated into any block.
    *
    * @param transactionHash
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async rebroadcastPendingTransaction(transactionHash, options) {
+  async rebroadcastPendingTransaction(transactionHash, requestOptions) {
     transactionHash = new TransactionId(transactionHash);
-    return transactions.rebroadcastTransaction(this.getRequestOptionsForCall(options), transactionHash);
+    return transactions.rebroadcastTransaction(this.getRequestOptionsForCall(requestOptions), transactionHash);
   }
   /**
-   * Cancels a currently pending transaction
+   * Cancels a currently pending transaction.
+   *
    * @param transactionHash
    * @param gasPrice
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async cancelPendingTransaction(transactionHash, gasPrice, options) {
+  async cancelPendingTransaction(transactionHash, gasPrice, requestOptions) {
     transactionHash = new TransactionId(transactionHash);
     let gasPriceString;
     if (gasPrice) {
@@ -1392,43 +1843,43 @@ export class Bee {
         name: 'gasPrice'
       });
     }
-    return transactions.cancelTransaction(this.getRequestOptionsForCall(options), transactionHash, gasPriceString);
+    return transactions.cancelTransaction(this.getRequestOptionsForCall(requestOptions), transactionHash, gasPriceString);
   }
   /**
-   * Gets the amount of staked BZZ
+   * Gets the amount of staked BZZ.
    *
-   * @param options HTTP request options, such as `headers` or `timeout`
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getStake(options) {
-    return stake.getStake(this.getRequestOptionsForCall(options));
+  async getStake(requestOptions) {
+    return stake.getStake(this.getRequestOptionsForCall(requestOptions));
   }
   /**
    * Gets the amount of withdrawable staked BZZ.
    *
-   * @param options HTTP request options, such as `headers` or `timeout`
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async getWithdrawableStake(options) {
-    return stake.getWithdrawableStake(this.getRequestOptionsForCall(options));
+  async getWithdrawableStake(requestOptions) {
+    return stake.getWithdrawableStake(this.getRequestOptionsForCall(requestOptions));
   }
   /**
-   * Withdraws ALL surplus staked BZZ to the node wallet.
+   * Withdraws all surplus staked BZZ to the node wallet.
    *
-   * Use the `getWithdrawableStake` method to check how much surplus stake is available.
+   * Use the {@link getWithdrawableStake} method to check how much surplus stake is available.
    *
-   * @param options HTTP request options, such as `headers` or `timeout`
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async withdrawSurplusStake(options) {
-    return stake.withdrawSurplusStake(this.getRequestOptionsForCall(options));
+  async withdrawSurplusStake(requestOptions) {
+    return stake.withdrawSurplusStake(this.getRequestOptionsForCall(requestOptions));
   }
   /**
    * Withdraws all staked BZZ to the node wallet.
    *
    * **Only available when the staking contract is paused and is in the process of being migrated to a new contract!**
    *
-   * @param options HTTP request options, such as `headers` or `timeout`
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
-  async migrateStake(options) {
-    return stake.migrateStake(this.getRequestOptionsForCall(options));
+  async migrateStake(requestOptions) {
+    return stake.migrateStake(this.getRequestOptionsForCall(requestOptions));
   }
   /**
    * Stakes the given amount of BZZ. Initial deposit must be at least 10 BZZ.
@@ -1436,7 +1887,8 @@ export class Bee {
    * Be aware that staked BZZ tokens can **not** be withdrawn.
    *
    * @param amount Amount of BZZ tokens to be staked. If not providing a `BZZ` instance, the amount is denoted in PLUR.
-   * @param options HTTP request options, such as `headers` or `timeout`
+   * @param options
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    */
   async depositStake(amount, options, requestOptions) {
     const amountString = amount instanceof BZZ ? amount.toPLURString() : asNumberString(amount, {
@@ -1449,12 +1901,14 @@ export class Bee {
     return stake.stake(this.getRequestOptionsForCall(requestOptions), amountString, options);
   }
   /**
-   * Gets current status of node in redistribution game
+   * Gets current status of node in redistribution game.
    *
-   * @param options HTTP request options, such as `headers` or `timeout`
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   *
+   * @see [Bee API reference - `GET /redistributionstate`](https://docs.ethswarm.org/api/#tag/RedistributionState/paths/~1redistributionstate/get)
    */
-  async getRedistributionState(options) {
-    return stake.getRedistributionState(this.getRequestOptionsForCall(options));
+  async getRedistributionState(requestOptions) {
+    return stake.getRedistributionState(this.getRequestOptionsForCall(requestOptions));
   }
   async waitForUsablePostageStamp(id, timeout = 240000) {
     const TIME_STEP = 3000;
@@ -1471,10 +1925,10 @@ export class Bee {
     }
     throw new BeeError('Timeout on waiting for postage stamp to become usable');
   }
-  getRequestOptionsForCall(options) {
-    if (options) {
-      options = prepareBeeRequestOptions(options);
+  getRequestOptionsForCall(requestOptions) {
+    if (requestOptions) {
+      requestOptions = prepareBeeRequestOptions(requestOptions);
     }
-    return options ? Objects.deepMerge2(this.requestOptions, options) : this.requestOptions;
+    return requestOptions ? Objects.deepMerge2(this.requestOptions, requestOptions) : this.requestOptions;
   }
 }