@upcoming/bee-js 9.9.0 → 10.1.2

package/dist/cjs/bee.js

@@ -66,21 +66,23 @@ const type_1 = require("./utils/type");
 const typed_bytes_1 = require("./utils/typed-bytes");
 const url_1 = require("./utils/url");
 /**
- * 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')
  */
 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) {
         (0, url_1.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 = (0, url_1.stripLastSlash)(url);
         if (options?.signer) {
             this.signer = new typed_bytes_1.PrivateKey(options.signer);
@@ -96,15 +98,19 @@ 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 typed_bytes_1.BatchId(postageBatchId);
@@ -115,21 +121,32 @@ 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 typed_bytes_1.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)
      */
@@ -140,12 +157,18 @@ class Bee {
         return bytes.download(this.getRequestOptionsForCall(requestOptions), new resource_locator_1.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)
      */
@@ -156,11 +179,14 @@ class Bee {
         return bytes.downloadReadable(this.getRequestOptionsForCall(requestOptions), new resource_locator_1.ResourceLocator(resource), options);
     }
     /**
-     * Upload chunk to a Bee node
+     * Uploads a chunk to the network.
+     *
+     * Chunks uploaded with this method should be retrieved with the {@link downloadChunk} method.
      *
-     * @param postageBatchId Postage BatchId to be used to upload the chunk with
+     * @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)
@@ -180,12 +206,17 @@ 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)
      */
@@ -199,7 +230,7 @@ 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.
@@ -229,7 +260,7 @@ 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) {
@@ -243,12 +274,18 @@ 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)
@@ -276,14 +313,13 @@ 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)
      */
@@ -299,8 +335,7 @@ 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)
@@ -323,6 +358,7 @@ 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)
@@ -336,13 +372,57 @@ class Bee {
         const data = (0, collection_1.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 (0, chunk_stream_1.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 typed_bytes_1.BatchId(postageBatchId);
         return (0, chunk_stream_1.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 typed_bytes_1.BatchId(postageBatchId);
         return (0, chunk_stream_1.streamFiles)(this, files, postageBatchId, onUploadProgress, options, this.getRequestOptionsForCall(requestOptions));
@@ -390,23 +470,23 @@ 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)
@@ -418,34 +498,31 @@ 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 = (0, type_1.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 = (0, type_1.makeTagUid)(tagUid);
-        return tag.deleteTag(this.getRequestOptionsForCall(options), tagUid);
+        return tag.deleteTag(this.getRequestOptionsForCall(requestOptions), tagUid);
     }
     /**
      * Update tag's total chunks count.
@@ -455,99 +532,90 @@ 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 typed_bytes_1.Reference(reference);
         tagUid = (0, type_1.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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.BatchId(postageBatchId);
         reference = new typed_bytes_1.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 typed_bytes_1.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.
@@ -560,6 +628,7 @@ 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 typed_bytes_1.EthAddress(owner);
@@ -590,36 +659,33 @@ 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 typed_bytes_1.BatchId(postageBatchId);
         (0, type_1.assertData)(data);
         if (recipient) {
             recipient = new typed_bytes_1.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
@@ -634,17 +700,14 @@ 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 = {
@@ -658,28 +721,24 @@ class Bee {
             }
         };
         ws.onerror = event => {
-            // ignore errors after subscription was cancelled
             if (!cancelled) {
                 handler.onError(new error_1.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
@@ -706,6 +765,10 @@ class Bee {
                     subscription.cancel();
                     resolve(message);
                 },
+                onClose: () => {
+                    clearTimeout(timeout);
+                    subscription.cancel();
+                },
             });
             if (timeoutMsec > 0) {
                 timeout = setTimeout(() => {
@@ -715,6 +778,22 @@ 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 typed_bytes_1.PeerAddress(targetOverlay);
         identifier = new typed_bytes_1.Identifier(identifier);
@@ -730,6 +809,29 @@ 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 typed_bytes_1.BatchId(postageBatchId);
         signer = new typed_bytes_1.PrivateKey(signer);
@@ -738,6 +840,37 @@ class Bee {
         const soc = (0, soc_1.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 typed_bytes_1.EthAddress(address);
         identifier = new typed_bytes_1.Identifier(identifier);
@@ -746,7 +879,7 @@ 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();
@@ -771,17 +904,21 @@ class Bee {
                 handler.onError(new error_1.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)
@@ -796,35 +933,35 @@ class Bee {
         return (0, feed_2.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 typed_bytes_1.Topic(topic);
         owner = new typed_bytes_1.EthAddress(owner);
-        return (0, feed_1.makeFeedReader)(this.getRequestOptionsForCall(options), topic, owner);
+        return (0, feed_1.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 typed_bytes_1.Topic(topic);
         signer = signer ? new typed_bytes_1.PrivateKey(signer) : this.signer;
         if (!signer) {
             throw Error('No signer provided');
         }
-        return (0, feed_1.makeFeedWriter)(this.getRequestOptionsForCall(options), topic, signer);
+        return (0, feed_1.makeFeedWriter)(this.getRequestOptionsForCall(requestOptions), topic, signer);
     }
     async fetchLatestFeedUpdate(topic, owner, requestOptions) {
         topic = new typed_bytes_1.Topic(topic);
@@ -835,62 +972,91 @@ 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 typed_bytes_1.EthAddress(ownerAddress);
         return {
             owner: ownerAddress,
-            download: soc_1.downloadSingleOwnerChunk.bind(null, this.getRequestOptionsForCall(options), ownerAddress),
+            download: soc_1.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 typed_bytes_1.PrivateKey(signer) : this.signer;
         if (!signer) {
             throw Error('No signer provided');
         }
         return {
-            ...this.makeSOCReader(signer.publicKey().address(), options),
-            upload: soc_1.uploadSingleOwnerChunkData.bind(null, this.getRequestOptionsForCall(options), signer),
+            ...this.makeSOCReader(signer.publicKey().address(), requestOptions),
+            upload: soc_1.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 typed_bytes_1.BatchId(postageBatchId);
         reference = new typed_bytes_1.Reference(reference);
-        return (0, envelope_1.postEnvelope)(this.getRequestOptionsForCall(options), postageBatchId, reference);
+        return (0, envelope_1.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 (0, rchash_1.rchash)(this.getRequestOptionsForCall(options), depth, anchor1, anchor2);
+    async rchash(depth, anchor1, anchor2, requestOptions) {
+        return (0, rchash_1.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;
@@ -903,117 +1069,170 @@ 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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.PeerAddress(address);
@@ -1023,117 +1242,151 @@ 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 tokens_1.BZZ ? amount.toPLURString() : (0, type_1.asNumberString)(amount, { min: 1n, name: 'amount' });
         let gasPriceString;
         if (gasPrice) {
             gasPriceString = (0, type_1.asNumberString)(amount, { min: 0n, 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 tokens_1.BZZ ? amount.toPLURString() : (0, type_1.asNumberString)(amount, { min: 1n, name: 'amount' });
         let gasPriceString;
         if (gasPrice) {
             gasPriceString = (0, type_1.asNumberString)(amount, { min: 0n, 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 tokens_1.BZZ ? amount : tokens_1.BZZ.fromPLUR(amount);
         address = new typed_bytes_1.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 tokens_1.DAI ? amount : tokens_1.DAI.fromWei(amount);
         address = new typed_bytes_1.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 typed_bytes_1.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));
     }
     /**
      *
@@ -1141,53 +1394,56 @@ 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)
@@ -1211,6 +1467,24 @@ class Bee {
         }
         return stamp;
     }
+    /**
+     * 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 = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
@@ -1220,238 +1494,399 @@ class Bee {
         }
         return this.createPostageBatch(amount, depth, options, requestOptions);
     }
-    async getStorageCost(size, duration, options, encryption, erasureCodeLevel) {
-        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 = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
         const depth = (0, stamps_1.getDepthForSize)(size, encryption, erasureCodeLevel);
         return (0, stamps_1.getStampCost)(depth, amount);
     }
-    async extendStorage(postageBatchId, size, duration, options, encryption, erasureCodeLevel) {
-        const batch = await this.getPostageBatch(postageBatchId, options);
+    /**
+     * 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 = (0, stamps_1.getDepthForSize)(size, encryption, erasureCodeLevel);
-        const chainState = await this.getChainState(options);
+        const chainState = await this.getChainState(requestOptions);
         const depthDelta = depth - batch.depth;
-        const multiplier = depthDelta === 0 ? 1n : 2n ** BigInt(depthDelta);
-        const additionalAmount = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
-        const targetAmount = duration.isZero()
-            ? BigInt(batch.amount) * multiplier
-            : (BigInt(batch.amount) + additionalAmount) * multiplier;
-        const amountDelta = targetAmount - BigInt(batch.amount);
-        const transactionId = await this.topUpBatch(batch.batchID, amountDelta, options);
-        if (depthDelta) {
-            return this.diluteBatch(batch.batchID, depth, options);
+        const multiplier = depthDelta <= 0 ? 1n : 2n ** BigInt(depthDelta);
+        const blockTime = this.network === 'gnosis' ? 5 : 15;
+        const additionalAmount = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice, blockTime);
+        const currentAmount = (0, stamps_1.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;
     }
-    async extendStorageSize(postageBatchId, size, options, encryption, erasureCodeLevel) {
-        const batch = await this.getPostageBatch(postageBatchId, options);
+    /**
+     * 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 = (0, stamps_1.getDepthForSize)(size, encryption, erasureCodeLevel);
         const delta = depth - batch.depth;
         if (delta <= 0) {
             throw new error_1.BeeArgumentError('New depth has to be greater than the original depth', depth);
         }
-        await this.topUpBatch(batch.batchID, BigInt(batch.amount) * (2n ** BigInt(delta) - 1n) + 1n, options);
-        return this.diluteBatch(batch.batchID, depth, options);
+        const currentAmount = (0, stamps_1.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 = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
-        return this.topUpBatch(batch.batchID, amount, options);
-    }
-    async getExtensionCost(postageBatchId, size, duration, options, encryption, erasureCodeLevel) {
-        const batch = await this.getPostageBatch(postageBatchId, options);
-        const chainState = await this.getChainState(options);
-        const amount = duration.isZero()
-            ? 0n
-            : (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
+        return this.topUpBatch(batch.batchID, amount, requestOptions);
+    }
+    /**
+     * 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 : (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice, blockTime);
         const depth = (0, stamps_1.getDepthForSize)(size, encryption, erasureCodeLevel);
-        const currentCost = (0, stamps_1.getStampCost)(batch.depth, batch.amount);
-        const newCost = (0, stamps_1.getStampCost)(depth, BigInt(batch.amount) + amount);
+        const currentAmount = (0, stamps_1.getAmountForDuration)(batch.duration, chainState.currentPrice, blockTime);
+        const currentCost = (0, stamps_1.getStampCost)(batch.depth, currentAmount);
+        const newCost = (0, stamps_1.getStampCost)(Math.max(batch.depth, depth), currentAmount + amount);
         return newCost.minus(currentCost);
     }
-    async getSizeExtensionCost(postageBatchId, size, options, encryption, erasureCodeLevel) {
-        const batch = await this.getPostageBatch(postageBatchId, options);
+    /**
+     * 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 = (0, stamps_1.getDepthForSize)(size, encryption, erasureCodeLevel);
         const delta = depth - batch.depth;
         if (delta <= 0) {
             throw new error_1.BeeArgumentError('New depth has to be greater than the original depth', depth);
         }
-        const currentCost = (0, stamps_1.getStampCost)(batch.depth, batch.amount);
-        const newCost = (0, stamps_1.getStampCost)(depth, batch.amount);
+        const currentAmount = (0, stamps_1.getAmountForDuration)(batch.duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
+        const currentCost = (0, stamps_1.getStampCost)(batch.depth, currentAmount);
+        const newCost = (0, stamps_1.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 = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice, this.network === 'gnosis' ? 5 : 15);
         return (0, stamps_1.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 typed_bytes_1.BatchId(postageBatchId);
         const amountString = (0, type_1.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 typed_bytes_1.BatchId(postageBatchId);
         depth = cafe_utility_1.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.
+     * @param encryption Assume that uploads with this postage batch are encrypted, which skews the capacity.
+     * @param erasureCodeLevel Assume that uploads with this postage batch are erasure coded, which skews the capacity.
      *
      * @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, encryption, erasureCodeLevel) {
         postageBatchId = new typed_bytes_1.BatchId(postageBatchId);
-        return stamps.getPostageBatch(this.getRequestOptionsForCall(options), postageBatchId);
+        return stamps.getPostageBatch(this.getRequestOptionsForCall(requestOptions), postageBatchId, encryption, erasureCodeLevel);
     }
     /**
      * 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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.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 typed_bytes_1.TransactionId(transactionHash);
         let gasPriceString;
         if (gasPrice) {
             gasPriceString = (0, type_1.asNumberString)(gasPrice, { min: 0n, 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.
@@ -1459,7 +1894,8 @@ 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 tokens_1.BZZ ? amount.toPLURString() : (0, type_1.asNumberString)(amount, { min: 1n, name: 'amount' });
@@ -1469,12 +1905,14 @@ 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;
@@ -1492,11 +1930,11 @@ class Bee {
         }
         throw new error_1.BeeError('Timeout on waiting for postage stamp to become usable');
     }
-    getRequestOptionsForCall(options) {
-        if (options) {
-            options = (0, type_1.prepareBeeRequestOptions)(options);
+    getRequestOptionsForCall(requestOptions) {
+        if (requestOptions) {
+            requestOptions = (0, type_1.prepareBeeRequestOptions)(requestOptions);
         }
-        return options ? cafe_utility_1.Objects.deepMerge2(this.requestOptions, options) : this.requestOptions;
+        return requestOptions ? cafe_utility_1.Objects.deepMerge2(this.requestOptions, requestOptions) : this.requestOptions;
     }
 }
 exports.Bee = Bee;