@ethersphere/bee-js 3.2.0 → 3.3.0

package/dist/mjs/modules/bzz.js

@@ -0,0 +1,119 @@
+import { extractUploadHeaders, readFileHeaders } from '../utils/headers';
+import { http } from '../utils/http';
+import { prepareData } from '../utils/data';
+import { makeTar } from '../utils/tar';
+import { assertCollection } from '../utils/collection';
+import { wrapBytesWithHelpers } from '../utils/bytes';
+import { isReadable } from '../utils/stream';
+import { makeTagUid } from '../utils/type';
+const bzzEndpoint = 'bzz';
+function extractFileUploadHeaders(postageBatchId, options) {
+    const headers = extractUploadHeaders(postageBatchId, options);
+    if (options?.size)
+        headers['content-length'] = String(options.size);
+    if (options?.contentType)
+        headers['content-type'] = options.contentType;
+    return headers;
+}
+/**
+ * Upload single file
+ *
+ * @param ky
+ * @param data Files data
+ * @param postageBatchId  Postage BatchId that will be assigned to uploaded data
+ * @param name Name that will be attached to the uploaded file. Wraps the data into manifest with set index document.
+ * @param options
+ */
+export async function uploadFile(ky, data, postageBatchId, name, options) {
+    if (isReadable(data) && !options?.contentType) {
+        if (!options)
+            options = {};
+        options.contentType = 'application/octet-stream';
+    }
+    const response = await http(ky, {
+        method: 'post',
+        path: bzzEndpoint,
+        body: await prepareData(data),
+        headers: {
+            ...extractFileUploadHeaders(postageBatchId, options),
+        },
+        searchParams: { name },
+        responseType: 'json',
+    });
+    return {
+        reference: response.data.reference,
+        tagUid: makeTagUid(response.headers.get('swarm-tag')),
+    };
+}
+/**
+ * Download single file as a buffer
+ *
+ * @param ky Ky instance for given Bee class instance
+ * @param hash Bee file or collection hash
+ * @param path If hash is collection then this defines path to a single file in the collection
+ */
+export async function downloadFile(ky, hash, path = '') {
+    const response = await http(ky, {
+        method: 'GET',
+        responseType: 'arraybuffer',
+        path: `${bzzEndpoint}/${hash}/${path}`,
+    });
+    const file = {
+        ...readFileHeaders(response.headers),
+        data: wrapBytesWithHelpers(new Uint8Array(response.data)),
+    };
+    return file;
+}
+/**
+ * Download single file as a readable stream
+ *
+ * @param ky Ky instance for given Bee class instance
+ * @param hash Bee file or collection hash
+ * @param path If hash is collection then this defines path to a single file in the collection
+ */
+export async function downloadFileReadable(ky, hash, path = '') {
+    const response = await http(ky, {
+        method: 'GET',
+        responseType: 'stream',
+        path: `${bzzEndpoint}/${hash}/${path}`,
+    });
+    const file = {
+        ...readFileHeaders(response.headers),
+        data: response.data,
+    };
+    return file;
+}
+function extractCollectionUploadHeaders(postageBatchId, options) {
+    const headers = extractUploadHeaders(postageBatchId, options);
+    if (options?.indexDocument)
+        headers['swarm-index-document'] = options.indexDocument;
+    if (options?.errorDocument)
+        headers['swarm-error-document'] = options.errorDocument;
+    return headers;
+}
+/**
+ * Upload collection
+ * @param ky Ky instance for given Bee class instance
+ * @param collection Collection of Uint8Array buffers to upload
+ * @param postageBatchId  Postage BatchId that will be assigned to uploaded data
+ * @param options
+ */
+export async function uploadCollection(ky, collection, postageBatchId, options) {
+    assertCollection(collection);
+    const tarData = makeTar(collection);
+    const response = await http(ky, {
+        method: 'post',
+        path: bzzEndpoint,
+        body: tarData,
+        responseType: 'json',
+        headers: {
+            'content-type': 'application/x-tar',
+            'swarm-collection': 'true',
+            ...extractCollectionUploadHeaders(postageBatchId, options),
+        },
+    });
+    return {
+        reference: response.data.reference,
+        tagUid: makeTagUid(response.headers.get('swarm-tag')),
+    };
+}

package/dist/mjs/modules/chunk.js

@@ -0,0 +1,43 @@
+import { extractUploadHeaders } from '../utils/headers';
+import { http } from '../utils/http';
+import { wrapBytesWithHelpers } from '../utils/bytes';
+const endpoint = 'chunks';
+/**
+ * Upload chunk to a Bee node
+ *
+ * The chunk data consists of 8 byte span and up to 4096 bytes of payload data.
+ * The span stores the length of the payload in uint64 little endian encoding.
+ * Upload expects the chuck data to be set accordingly.
+ *
+ * @param ky Ky instance
+ * @param data    Chunk data to be uploaded
+ * @param postageBatchId  Postage BatchId that will be assigned to uploaded data
+ * @param options Additional options like tag, encryption, pinning
+ */
+export async function upload(ky, data, postageBatchId, options) {
+    const response = await http(ky, {
+        method: 'post',
+        path: `${endpoint}`,
+        body: data,
+        headers: {
+            'content-type': 'application/octet-stream',
+            ...extractUploadHeaders(postageBatchId, options),
+        },
+        responseType: 'json',
+    });
+    return response.data.reference;
+}
+/**
+ * Download chunk data as a byte array
+ *
+ * @param ky Ky instance for given Bee class instance
+ * @param hash Bee content reference
+ *
+ */
+export async function download(ky, hash) {
+    const response = await http(ky, {
+        responseType: 'arraybuffer',
+        path: `${endpoint}/${hash}`,
+    });
+    return wrapBytesWithHelpers(new Uint8Array(response.data));
+}

package/dist/mjs/modules/debug/balance.js

@@ -0,0 +1,53 @@
+import { http } from '../../utils/http';
+const balancesEndpoint = 'balances';
+const consumedEndpoint = 'consumed';
+/**
+ * Get the balances with all known peers including prepaid services
+ *
+ * @param ky Ky debug instance
+ */
+export async function getAllBalances(ky) {
+    const response = await http(ky, {
+        path: balancesEndpoint,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get the balances with a specific peer including prepaid services
+ *
+ * @param ky Ky debug instance
+ * @param address Swarm address of peer
+ */
+export async function getPeerBalance(ky, address) {
+    const response = await http(ky, {
+        path: `${balancesEndpoint}/${address}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get the past due consumption balances with all known peers
+ *
+ * @param ky Ky debug instance
+ */
+export async function getPastDueConsumptionBalances(ky) {
+    const response = await http(ky, {
+        path: consumedEndpoint,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get the past due consumption balance with a specific peer
+ *
+ * @param ky Ky debug instance
+ * @param address Swarm address of peer
+ */
+export async function getPastDueConsumptionPeerBalance(ky, address) {
+    const response = await http(ky, {
+        path: `${consumedEndpoint}/${address}`,
+        responseType: 'json',
+    });
+    return response.data;
+}

package/dist/mjs/modules/debug/chequebook.js

@@ -0,0 +1,131 @@
+import { http } from '../../utils/http';
+const chequebookEndpoint = 'chequebook';
+/**
+ * Get the address of the chequebook contract used
+ *
+ * @param ky Ky debug instance
+ */
+export async function getChequebookAddress(ky) {
+    const response = await http(ky, {
+        path: chequebookEndpoint + '/address',
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get the balance of the chequebook
+ *
+ * @param ky Ky debug instance
+ */
+export async function getChequebookBalance(ky) {
+    const response = await http(ky, {
+        path: chequebookEndpoint + '/balance',
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get last cashout action for the peer
+ *
+ * @param ky Ky debug instance
+ * @param peer  Swarm address of peer
+ */
+export async function getLastCashoutAction(ky, peer) {
+    const response = await http(ky, {
+        path: chequebookEndpoint + `/cashout/${peer}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Cashout the last cheque for the peer
+ *
+ * @param ky Ky debug instance
+ * @param peer  Swarm address of peer
+ * @param options
+ */
+export async function cashoutLastCheque(ky, peer, options) {
+    const headers = {};
+    if (options?.gasPrice) {
+        headers['gas-price'] = options.gasPrice.toString();
+    }
+    if (options?.gasLimit) {
+        headers['gas-limit'] = options.gasLimit.toString();
+    }
+    const response = await http(ky, {
+        method: 'post',
+        path: chequebookEndpoint + `/cashout/${peer}`,
+        responseType: 'json',
+        headers,
+    });
+    return response.data.transactionHash;
+}
+/**
+ * Get last cheques for the peer
+ *
+ * @param ky Ky debug instance
+ * @param peer  Swarm address of peer
+ */
+export async function getLastChequesForPeer(ky, peer) {
+    const response = await http(ky, {
+        path: chequebookEndpoint + `/cheque/${peer}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get last cheques for all peers
+ *
+ * @param ky Ky debug instance
+ */
+export async function getLastCheques(ky) {
+    const response = await http(ky, {
+        path: chequebookEndpoint + '/cheque',
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Deposit tokens from overlay address into chequebook
+ *
+ * @param ky Ky debug instance
+ * @param amount   Amount of tokens to deposit
+ * @param gasPrice Gas Price in WEI for the transaction call
+ * @return string  Hash of the transaction
+ */
+export async function depositTokens(ky, amount, gasPrice) {
+    const headers = {};
+    if (gasPrice) {
+        headers['gas-price'] = gasPrice.toString();
+    }
+    const response = await http(ky, {
+        method: 'post',
+        path: chequebookEndpoint + '/deposit',
+        responseType: 'json',
+        searchParams: { amount: amount.toString(10) },
+        headers,
+    });
+    return response.data.transactionHash;
+}
+/**
+ * Withdraw tokens from the chequebook to the overlay address
+ *
+ * @param ky Ky debug instance
+ * @param amount   Amount of tokens to withdraw
+ * @param gasPrice Gas Price in WEI for the transaction call
+ * @return string  Hash of the transaction
+ */
+export async function withdrawTokens(ky, amount, gasPrice) {
+    const headers = {};
+    if (gasPrice) {
+        headers['gas-price'] = gasPrice.toString();
+    }
+    const response = await http(ky, {
+        method: 'post',
+        path: chequebookEndpoint + '/withdraw',
+        responseType: 'json',
+        searchParams: { amount: amount.toString(10) },
+        headers,
+    });
+    return response.data.transactionHash;
+}

package/dist/mjs/modules/debug/chunk.js

@@ -0,0 +1,33 @@
+import { http } from '../../utils/http';
+const endpoint = 'chunks';
+/**
+ * Check if chunk at address exists locally
+ *
+ * @param ky Ky debug instance
+ * @param address  Swarm address of chunk
+ *
+ * @returns BeeGenericResponse if chunk is found or throws an exception
+ */
+export async function checkIfChunkExistsLocally(ky, address) {
+    const response = await http(ky, {
+        path: endpoint + `/${address}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Delete a chunk from local storage
+ *
+ * @param ky Ky debug instance
+ * @param address  Swarm address of chunk
+ *
+ * @returns BeeGenericResponse if chunk was deleted or throws an exception
+ */
+export async function deleteChunkFromLocalStorage(ky, address) {
+    const response = await http(ky, {
+        method: 'delete',
+        path: endpoint + `/${address}`,
+        responseType: 'json',
+    });
+    return response.data;
+}

package/dist/mjs/modules/debug/connectivity.js

@@ -0,0 +1,45 @@
+import { http } from '../../utils/http';
+export async function getNodeAddresses(ky) {
+    const response = await http(ky, {
+        path: 'addresses',
+        responseType: 'json',
+    });
+    return response.data;
+}
+export async function getPeers(ky) {
+    const response = await http(ky, {
+        path: 'peers',
+        responseType: 'json',
+    });
+    return response.data.peers || [];
+}
+export async function getBlocklist(ky) {
+    const response = await http(ky, {
+        path: 'blocklist',
+        responseType: 'json',
+    });
+    return response.data.peers || [];
+}
+export async function removePeer(ky, peer) {
+    const response = await http(ky, {
+        path: `peers/${peer}`,
+        responseType: 'json',
+        method: 'DELETE',
+    });
+    return response.data;
+}
+export async function getTopology(ky) {
+    const response = await http(ky, {
+        path: `topology`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+export async function pingPeer(ky, peer) {
+    const response = await http(ky, {
+        path: `pingpong/${peer}`,
+        responseType: 'json',
+        method: 'POST',
+    });
+    return response.data;
+}

package/dist/mjs/modules/debug/settlements.js

@@ -0,0 +1,27 @@
+import { http } from '../../utils/http';
+const settlementsEndpoint = 'settlements';
+/**
+ * Get amount of sent and received from settlements with a peer
+ *
+ * @param ky Ky debug instance
+ * @param peer  Swarm address of peer
+ */
+export async function getSettlements(ky, peer) {
+    const response = await http(ky, {
+        path: `${settlementsEndpoint}/${peer}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get settlements with all known peers and total amount sent or received
+ *
+ * @param ky Ky debug instance
+ */
+export async function getAllSettlements(ky) {
+    const response = await http(ky, {
+        path: settlementsEndpoint,
+        responseType: 'json',
+    });
+    return response.data;
+}

package/dist/mjs/modules/debug/stamps.js

@@ -0,0 +1,59 @@
+import { http } from '../../utils/http';
+const STAMPS_ENDPOINT = 'stamps';
+export async function getAllPostageBatches(ky) {
+    const response = await http(ky, {
+        method: 'get',
+        path: `${STAMPS_ENDPOINT}`,
+        responseType: 'json',
+    });
+    return response.data.stamps || [];
+}
+export async function getPostageBatch(ky, postageBatchId) {
+    const response = await http(ky, {
+        method: 'get',
+        path: `${STAMPS_ENDPOINT}/${postageBatchId}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+export async function getPostageBatchBuckets(ky, postageBatchId) {
+    const response = await http(ky, {
+        method: 'get',
+        path: `${STAMPS_ENDPOINT}/${postageBatchId}/buckets`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+export async function createPostageBatch(ky, amount, depth, options) {
+    const headers = {};
+    if (options?.gasPrice) {
+        headers['gas-price'] = options.gasPrice.toString();
+    }
+    if (options?.immutableFlag !== undefined) {
+        headers.immutable = String(options.immutableFlag);
+    }
+    const response = await http(ky, {
+        method: 'post',
+        path: `${STAMPS_ENDPOINT}/${amount}/${depth}`,
+        responseType: 'json',
+        searchParams: { label: options?.label },
+        headers,
+    });
+    return response.data.batchID;
+}
+export async function topUpBatch(ky, id, amount) {
+    const response = await http(ky, {
+        method: 'patch',
+        path: `${STAMPS_ENDPOINT}/topup/${id}/${amount}`,
+        responseType: 'json',
+    });
+    return response.data.batchID;
+}
+export async function diluteBatch(ky, id, depth) {
+    const response = await http(ky, {
+        method: 'patch',
+        path: `${STAMPS_ENDPOINT}/dilute/${id}/${depth}`,
+        responseType: 'json',
+    });
+    return response.data.batchID;
+}

package/dist/mjs/modules/debug/states.js

@@ -0,0 +1,29 @@
+import { http } from '../../utils/http';
+const RESERVE_STATE_ENDPOINT = 'reservestate';
+const CHAIN_STATE_ENDPOINT = 'chainstate';
+/**
+ * Get state of reserve
+ *
+ * @param ky Ky debug instance
+ */
+export async function getReserveState(ky) {
+    const response = await http(ky, {
+        method: 'get',
+        path: `${RESERVE_STATE_ENDPOINT}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get state of reserve
+ *
+ * @param ky Ky debug instance
+ */
+export async function getChainState(ky) {
+    const response = await http(ky, {
+        method: 'get',
+        path: `${CHAIN_STATE_ENDPOINT}`,
+        responseType: 'json',
+    });
+    return response.data;
+}

package/dist/mjs/modules/debug/status.js

@@ -0,0 +1,114 @@
+import { http } from '../../utils/http';
+import getMajorSemver from 'semver/functions/major';
+// Following lines bellow are automatically updated with GitHub Action when Bee version is updated
+// so if you are changing anything about them change the `update_bee` action accordingly!
+export const SUPPORTED_BEE_VERSION_EXACT = '1.4.3-1213e063';
+export const SUPPORTED_API_VERSION = '2.0.0';
+export const SUPPORTED_DEBUG_API_VERSION = '1.2.1';
+export const SUPPORTED_BEE_VERSION = SUPPORTED_BEE_VERSION_EXACT.substring(0, SUPPORTED_BEE_VERSION_EXACT.indexOf('-'));
+const NODE_INFO_URL = 'node';
+const HEALTH_URL = 'health';
+/**
+ * Get health of node
+ *
+ * @param ky Ky debug instance
+ */
+export async function getHealth(ky) {
+    const response = await http(ky, {
+        method: 'get',
+        path: HEALTH_URL,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get information about Bee node
+ *
+ * @param ky Ky debug instance
+ */
+export async function getNodeInfo(ky) {
+    const response = await http(ky, {
+        method: 'get',
+        path: NODE_INFO_URL,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Connects to a node and checks if it is a supported Bee version by the bee-js
+ *
+ * @param ky Ky debug instance
+ *
+ * @returns true if the Bee node version is supported
+ * @deprecated Use `isSupportedExactVersion` instead
+ */
+export async function isSupportedVersion(ky) {
+    return isSupportedExactVersion(ky);
+}
+/**
+ * Connects to a node and checks if its version matches with the one that bee-js supports.
+ *
+ * Be aware that this is the most strict version check and most probably
+ * you will want to use more relaxed API-versions based checks like
+ * `isSupportedApiVersion`, `isSupportedMainApiVersion` or `isSupportedDebugApiVersion`
+ * based on your use-case.
+ *
+ * @param ky
+ */
+export async function isSupportedExactVersion(ky) {
+    const { version } = await getHealth(ky);
+    return version === SUPPORTED_BEE_VERSION_EXACT;
+}
+/**
+ * Connects to a node and checks if its main's API version matches with the one that bee-js supports.
+ *
+ * This is useful if you are not using `BeeDebug` class (for anything else then this check)
+ * and want to make sure about compatibility.
+ *
+ * @param ky
+ */
+export async function isSupportedMainApiVersion(ky) {
+    const { apiVersion } = await getHealth(ky);
+    return getMajorSemver(apiVersion) === getMajorSemver(SUPPORTED_API_VERSION);
+}
+/**
+ * Connects to a node and checks if its Debug API version matches with the one that bee-js supports.
+ *
+ * This is useful if you are not using `Bee` class in your application and want to make sure
+ * about compatibility.
+ *
+ * @param ky
+ */
+export async function isSupportedDebugApiVersion(ky) {
+    const { debugApiVersion } = await getHealth(ky);
+    return getMajorSemver(debugApiVersion) === getMajorSemver(SUPPORTED_DEBUG_API_VERSION);
+}
+/**
+ * Connects to a node and checks if its Main and Debug API versions matches with the one that bee-js supports.
+ *
+ * This should be the main way how to check compatibility for your app and Bee node.
+ *
+ * @param ky
+ */
+export async function isSupportedApiVersion(ky) {
+    const { apiVersion, debugApiVersion } = await getHealth(ky);
+    return (getMajorSemver(apiVersion) === getMajorSemver(SUPPORTED_API_VERSION) &&
+        getMajorSemver(debugApiVersion) === getMajorSemver(SUPPORTED_DEBUG_API_VERSION));
+}
+/**
+ * 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 ky
+ */
+export async function getVersions(ky) {
+    const { version, apiVersion, debugApiVersion } = await getHealth(ky);
+    return {
+        supportedBeeVersion: SUPPORTED_BEE_VERSION_EXACT,
+        supportedBeeApiVersion: SUPPORTED_API_VERSION,
+        supportedBeeDebugApiVersion: SUPPORTED_DEBUG_API_VERSION,
+        beeVersion: version,
+        beeApiVersion: apiVersion,
+        beeDebugApiVersion: debugApiVersion,
+    };
+}

package/dist/mjs/modules/debug/tag.js

@@ -0,0 +1,15 @@
+import { http } from '../../utils/http';
+const endpoint = 'tags';
+/**
+ * Retrieve tag with extended information from Bee node
+ *
+ * @param ky Ky debug instance
+ * @param uid UID of tag to be retrieved
+ */
+export async function retrieveExtendedTag(ky, uid) {
+    const response = await http(ky, {
+        path: `${endpoint}/${uid}`,
+        responseType: 'json',
+    });
+    return response.data;
+}