@ethersphere/bee-js 3.2.0 → 3.3.0

package/dist/mjs/utils/pss.js

@@ -0,0 +1,14 @@
+import { PSS_TARGET_HEX_LENGTH_MAX } from '../types';
+/**
+ * Utility function that for given strings/reference takes the most specific
+ * target that Bee node will except.
+ *
+ * @param target is a non-prefixed hex string Bee address
+ * @see [Bee docs - PSS](https://docs.ethswarm.org/docs/dapps-on-swarm/pss)
+ */
+export function makeMaxTarget(target) {
+    if (typeof target !== 'string') {
+        throw new TypeError('target has to be an string!');
+    }
+    return target.slice(0, PSS_TARGET_HEX_LENGTH_MAX);
+}

package/dist/mjs/utils/stamps.js

@@ -0,0 +1,13 @@
+/**
+ * Utility function that calculates usage of postage batch based on its utilization, depth and bucket depth.
+ *
+ * Be aware for small depths (17, 18) this does not provide that much information as the provided set of distinct values
+ * is small.
+ *
+ * @param utilization
+ * @param depth
+ * @param bucketDepth
+ */
+export function getStampUsage({ utilization, depth, bucketDepth }) {
+    return utilization / Math.pow(2, depth - bucketDepth);
+}

package/dist/mjs/utils/stream.js

@@ -0,0 +1,131 @@
+import { isStrictlyObject } from './type';
+import { ReadableStream } from 'web-streams-polyfill/ponyfill';
+import { Readable as NodeReadable } from 'readable-stream';
+/**
+ * Validates if passed object is either browser's ReadableStream
+ * or Node's Readable.
+ *
+ * @param entry
+ */
+export function isReadable(entry) {
+    return isReadableStream(entry) || isNodeReadable(entry);
+}
+export function isReadableStream(entry) {
+    if (!isStrictlyObject(entry)) {
+        return false;
+    }
+    const browserReadable = entry;
+    if (typeof browserReadable.getReader === 'function' &&
+        browserReadable.locked !== undefined &&
+        typeof browserReadable.cancel === 'function' &&
+        typeof browserReadable.pipeTo === 'function' &&
+        typeof browserReadable.pipeThrough === 'function') {
+        return true;
+    }
+    return false;
+}
+export function isNodeReadable(entry) {
+    if (!isStrictlyObject(entry)) {
+        return false;
+    }
+    const nodeReadable = entry;
+    if (typeof nodeReadable.pipe === 'function' && nodeReadable.readable && typeof nodeReadable._read === 'function') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Function that converts Node's Readable into WHATWG ReadableStream
+ *
+ * Taken over from https://github.com/gwicke/node-web-streams/blob/master/lib/conversions.js
+ * Because it uses forked web-streams-polyfill that are outdated.
+ *
+ * @author https://github.com/gwicke
+ * @licence Apache License 2.0 https://github.com/gwicke/node-web-streams/blob/master/LICENSE
+ * @param nodeStream
+ */
+export function readableNodeToWeb(nodeStream) {
+    return new ReadableStream({
+        start(controller) {
+            nodeStream.pause();
+            nodeStream.on('data', chunk => {
+                if (Buffer.isBuffer(chunk)) {
+                    controller.enqueue(new Uint8Array(chunk.buffer));
+                }
+                else {
+                    controller.enqueue(chunk);
+                }
+                nodeStream.pause();
+            });
+            nodeStream.on('end', () => controller.close());
+            nodeStream.on('error', e => controller.error(e));
+        },
+        pull() {
+            nodeStream.resume();
+        },
+        cancel() {
+            nodeStream.pause();
+        },
+    });
+}
+/**
+ * Taken over from https://github.com/gwicke/node-web-streams/blob/master/lib/conversions.js
+ * Because it uses forked web-streams-polyfill that are outdated.
+ *
+ * @author https://github.com/gwicke
+ * @licence Apache License 2.0 https://github.com/gwicke/node-web-streams/blob/master/LICENSE
+ */
+class NodeReadableWrapper extends NodeReadable {
+    _webStream;
+    _reader;
+    _reading;
+    constructor(webStream, options) {
+        super(options);
+        this._webStream = webStream;
+        this._reader = webStream.getReader();
+        this._reading = false;
+    }
+    _read() {
+        if (this._reading) {
+            return;
+        }
+        this._reading = true;
+        const doRead = () => {
+            this._reader.read().then(res => {
+                if (res.done) {
+                    this.push(null);
+                    return;
+                }
+                if (this.push(res.value)) {
+                    return doRead();
+                }
+                else {
+                    this._reading = false;
+                }
+            });
+        };
+        doRead();
+    }
+}
+/**
+ * Function that converts WHATWG ReadableStream into Node's Readable
+ *
+ * Taken over from https://github.com/gwicke/node-web-streams/blob/master/lib/conversions.js
+ * Because it uses forked web-streams-polyfill that are outdated.
+ *
+ * @author https://github.com/gwicke
+ * @licence Apache License 2.0 https://github.com/gwicke/node-web-streams/blob/master/LICENSE
+ * @param webStream
+ */
+export function readableWebToNode(webStream, options) {
+    return new NodeReadableWrapper(webStream, options);
+}
+export function normalizeToReadableStream(stream) {
+    if (isNodeReadable(stream)) {
+        return readableNodeToWeb(stream);
+    }
+    else if (isReadableStream(stream)) {
+        return stream;
+    }
+    throw new TypeError('Passed stream is not Node Readable nor ReadableStream!');
+}

package/dist/mjs/utils/tar.js

@@ -0,0 +1,18 @@
+import Tar from 'tar-js';
+// converts a string to utf8 Uint8Array and returns it as a string-like
+// object that `tar.append` accepts as path
+function fixUnicodePath(path) {
+    const codes = new TextEncoder().encode(path);
+    return {
+        length: codes.length,
+        charCodeAt: index => codes[index],
+    };
+}
+export function makeTar(data) {
+    const tar = new Tar();
+    for (const entry of data) {
+        const path = fixUnicodePath(entry.path);
+        tar.append(path, entry.data);
+    }
+    return tar.out;
+}

package/dist/mjs/utils/type.js

@@ -0,0 +1,296 @@
+import { ADDRESS_HEX_LENGTH, BATCH_ID_HEX_LENGTH, ENCRYPTED_REFERENCE_HEX_LENGTH, PUBKEY_HEX_LENGTH, REFERENCE_HEX_LENGTH, TAGS_LIMIT_MAX, TAGS_LIMIT_MIN, PSS_TARGET_HEX_LENGTH_MAX, } from '../types';
+import { BeeArgumentError } from './error';
+import { isFile } from './file';
+import { assertHexString, assertPrefixedHexString } from './hex';
+import { isReadable } from './stream';
+export function isUint8Array(obj) {
+    return obj instanceof Uint8Array;
+}
+export function isInteger(value) {
+    return ((typeof value === 'string' && /^-?(0|[1-9][0-9]*)$/g.test(value)) ||
+        (typeof value === 'number' &&
+            value > Number.MIN_SAFE_INTEGER &&
+            value < Number.MAX_SAFE_INTEGER &&
+            Number.isInteger(value)));
+}
+export function isObject(value) {
+    return value !== null && typeof value === 'object';
+}
+/**
+ * Generally it is discouraged to use `object` type, but in this case I think
+ * it is best to do so as it is possible to easily convert from `object`to other
+ * types, which will be usually the case after asserting that the object is
+ * strictly object. With for example Record<string, unknown> you have to first
+ * cast it to `unknown` which I think bit defeat the purpose.
+ *
+ * @param value
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function isStrictlyObject(value) {
+    return isObject(value) && !Array.isArray(value);
+}
+/**
+ * Asserts if object is Error
+ *
+ * @param e
+ */
+export function isError(e) {
+    return e instanceof Error;
+}
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function assertStrictlyObject(value, name = 'value') {
+    if (!isStrictlyObject(value)) {
+        throw new TypeError(`${name} has to be an object that is not null nor array!`);
+    }
+}
+export function assertBoolean(value, name = 'value') {
+    if (value !== true && value !== false)
+        throw new TypeError(`${name} is not boolean`);
+}
+export function assertInteger(value, name = 'value') {
+    if (!isInteger(value))
+        throw new TypeError(`${name} is not integer`);
+}
+export function assertNonNegativeInteger(value, name = 'Value') {
+    assertInteger(value, name);
+    if (Number(value) < 0)
+        throw new BeeArgumentError(`${name} has to be bigger or equal to zero`, value);
+}
+export function assertReference(value) {
+    try {
+        assertHexString(value, REFERENCE_HEX_LENGTH);
+    }
+    catch (e) {
+        assertHexString(value, ENCRYPTED_REFERENCE_HEX_LENGTH);
+    }
+}
+export function assertAddress(value) {
+    assertHexString(value, ADDRESS_HEX_LENGTH, 'Address');
+}
+export function assertBatchId(value) {
+    assertHexString(value, BATCH_ID_HEX_LENGTH, 'BatchId');
+}
+export function assertRequestOptions(value, name = 'RequestOptions') {
+    if (value === undefined) {
+        return;
+    }
+    if (!isStrictlyObject(value)) {
+        throw new TypeError(`${name} has to be an object!`);
+    }
+    const options = value;
+    if (options.retry) {
+        assertNonNegativeInteger(options.retry, `${name}.retry`);
+    }
+    if (options.timeout) {
+        assertNonNegativeInteger(options.timeout, `${name}.timeout`);
+    }
+    if (options.fetch && typeof options.fetch !== 'function') {
+        throw new TypeError(`${name}.fetch has to be a function or undefined!`);
+    }
+}
+export function assertUploadOptions(value, name = 'UploadOptions') {
+    if (!isStrictlyObject(value)) {
+        throw new TypeError(`${name} has to be an object!`);
+    }
+    assertRequestOptions(value, name);
+    const options = value;
+    if (options.pin && typeof options.pin !== 'boolean') {
+        throw new TypeError(`options.pin property in ${name} has to be boolean or undefined!`);
+    }
+    if (options.encrypt && typeof options.encrypt !== 'boolean') {
+        throw new TypeError(`options.encrypt property in ${name} has to be boolean or undefined!`);
+    }
+    if (options.tag) {
+        if (typeof options.tag !== 'number') {
+            throw new TypeError(`options.tag property in ${name} has to be number or undefined!`);
+        }
+        assertNonNegativeInteger(options.tag, 'options.tag');
+    }
+}
+export function assertFileUploadOptions(value) {
+    assertUploadOptions(value, 'FileUploadOptions');
+    const options = value;
+    if (options.size) {
+        if (typeof options.size !== 'number') {
+            throw new TypeError('tag property in FileUploadOptions has to be number or undefined!');
+        }
+        assertNonNegativeInteger(options.size, 'options.size');
+    }
+    if (options.contentType && typeof options.contentType !== 'string') {
+        throw new TypeError('contentType property in FileUploadOptions has to be string or undefined!');
+    }
+}
+export function assertCollectionUploadOptions(value) {
+    assertUploadOptions(value, 'CollectionUploadOptions');
+    const options = value;
+    if (options.indexDocument && typeof options.indexDocument !== 'string') {
+        throw new TypeError('indexDocument property in CollectionUploadOptions has to be string or undefined!');
+    }
+    if (options.errorDocument && typeof options.errorDocument !== 'string') {
+        throw new TypeError('errorDocument property in CollectionUploadOptions has to be string or undefined!');
+    }
+}
+export function isTag(value) {
+    if (!isStrictlyObject(value)) {
+        return false;
+    }
+    const tag = value;
+    const numberProperties = ['total', 'processed', 'synced', 'uid'];
+    const correctNumberProperties = numberProperties.every(numberProperty => typeof tag[numberProperty] === 'number');
+    if (!correctNumberProperties || !tag.startedAt || typeof tag.startedAt !== 'string') {
+        return false;
+    }
+    return true;
+}
+export function assertTag(value) {
+    if (!isStrictlyObject(value)) {
+        throw new TypeError('Tag is not an object!');
+    }
+    const tag = value;
+    const numberProperties = ['total', 'processed', 'synced', 'uid'];
+    for (const numberProperty of numberProperties) {
+        if (!tag[numberProperty]) {
+            throw new TypeError(`Tag's property '${numberProperty}' has to be specified!`);
+        }
+        if (typeof tag[numberProperty] !== 'number') {
+            throw new TypeError(`Tag's property '${numberProperty}' has to be number!`);
+        }
+    }
+    if (!tag.startedAt) {
+        throw new TypeError("Tag's property 'startedAt' has to be specified!");
+    }
+    if (typeof tag.startedAt !== 'string') {
+        throw new TypeError("Tag's property 'startedAt' has to be string!");
+    }
+}
+export function assertAddressPrefix(value) {
+    assertHexString(value, undefined, 'AddressPrefix');
+    if (value.length > PSS_TARGET_HEX_LENGTH_MAX) {
+        throw new BeeArgumentError(`AddressPrefix must have length of ${PSS_TARGET_HEX_LENGTH_MAX} at most! Got string with ${value.length}`, value);
+    }
+}
+export function assertPssMessageHandler(value) {
+    if (!isStrictlyObject(value)) {
+        throw new TypeError('PssMessageHandler has to be object!');
+    }
+    const handler = value;
+    if (typeof handler.onMessage !== 'function') {
+        throw new TypeError('onMessage property of PssMessageHandler has to be function!');
+    }
+    if (typeof handler.onError !== 'function') {
+        throw new TypeError('onError property of PssMessageHandler has to be function!');
+    }
+}
+export function assertPublicKey(value) {
+    assertHexString(value, PUBKEY_HEX_LENGTH, 'PublicKey');
+}
+export function assertPostageBatchOptions(value) {
+    if (value === undefined) {
+        return;
+    }
+    assertStrictlyObject(value);
+    const options = value;
+    assertRequestOptions(options, 'PostageBatchOptions');
+    if (options?.gasPrice) {
+        assertNonNegativeInteger(options.gasPrice);
+    }
+    if (options?.immutableFlag !== undefined) {
+        assertBoolean(options.immutableFlag);
+    }
+}
+export function assertCashoutOptions(value) {
+    if (value === undefined) {
+        return;
+    }
+    assertStrictlyObject(value);
+    const options = value;
+    assertRequestOptions(options, 'PostageBatchOptions');
+    if (options?.gasLimit) {
+        assertNonNegativeInteger(options.gasLimit);
+    }
+    if (options?.gasPrice) {
+        assertNonNegativeInteger(options.gasPrice);
+    }
+}
+/**
+ * Check whether the given parameter is valid data to upload
+ * @param value
+ * @throws TypeError if not valid
+ */
+export function assertData(value) {
+    if (typeof value !== 'string' && !(value instanceof Uint8Array)) {
+        throw new TypeError('Data must be either string or Uint8Array!');
+    }
+}
+/**
+ * Check whether the given parameter is a correct file representation to file upload.
+ * @param value
+ * @throws TypeError if not valid
+ */
+export function assertFileData(value) {
+    if (typeof value !== 'string' && !(value instanceof Uint8Array) && !isFile(value) && !isReadable(value)) {
+        throw new TypeError('Data must be either string, Readable, Uint8Array or File!');
+    }
+}
+/**
+ * Checks whether optional options for AllTags query are valid
+ * @param options
+ */
+export function assertAllTagsOptions(entry) {
+    if (entry !== undefined && !isStrictlyObject(entry)) {
+        throw new TypeError('options has to be an object or undefined!');
+    }
+    assertRequestOptions(entry, 'AllTagsOptions');
+    const options = entry;
+    if (options?.limit !== undefined) {
+        if (typeof options.limit !== 'number') {
+            throw new TypeError('AllTagsOptions.limit has to be a number or undefined!');
+        }
+        if (options.limit < TAGS_LIMIT_MIN) {
+            throw new BeeArgumentError(`AllTagsOptions.limit has to be at least ${TAGS_LIMIT_MIN}`, options.limit);
+        }
+        if (options.limit > TAGS_LIMIT_MAX) {
+            throw new BeeArgumentError(`AllTagsOptions.limit has to be at most ${TAGS_LIMIT_MAX}`, options.limit);
+        }
+    }
+    if (options?.offset !== undefined) {
+        assertNonNegativeInteger(options.offset, 'AllTagsOptions.offset');
+    }
+}
+/**
+ * Utility functions that return Tag UID
+ * @param tagUid
+ */
+export function makeTagUid(tagUid) {
+    if (tagUid === undefined || tagUid === null) {
+        throw new TypeError('TagUid was expected but got undefined or null instead!');
+    }
+    if (isTag(tagUid)) {
+        return tagUid.uid;
+    }
+    else if (typeof tagUid === 'number') {
+        assertNonNegativeInteger(tagUid, 'UID');
+        return tagUid;
+    }
+    else if (typeof tagUid === 'string') {
+        const int = parseInt(tagUid);
+        if (isNaN(int)) {
+            throw new TypeError('Passed tagUid string is not valid integer!');
+        }
+        if (int < 0) {
+            throw new TypeError(`TagUid was expected to be positive non-negative integer! Got ${int}`);
+        }
+        return int;
+    }
+    throw new TypeError('tagUid has to be either Tag or a number (UID)!');
+}
+export function assertTransactionHash(transactionHash) {
+    if (typeof transactionHash !== 'string') {
+        throw new TypeError('TransactionHash has to be a string!');
+    }
+    assertPrefixedHexString(transactionHash, 'TransactionHash');
+    // Hash is 64 long + '0x' prefix = 66
+    if (transactionHash.length !== 66) {
+        throw new TypeError('TransactionHash has to be prefixed hex string with total length 66 (prefix including)');
+    }
+}

package/dist/mjs/utils/uint64.js

@@ -0,0 +1,23 @@
+import { makeBytes } from './bytes';
+// TODO handle bigger values than 32 bit
+// For now it's good enough because we only use these functions
+// sequential feed indexes.
+export function writeUint64LittleEndian(value, bytes = makeBytes(8)) {
+    const dataView = new DataView(bytes.buffer);
+    const valueLower32 = value & 0xffffffff;
+    const littleEndian = true;
+    dataView.setUint32(0, valueLower32, littleEndian);
+    dataView.setUint32(4, 0, littleEndian);
+    return bytes;
+}
+export function writeUint64BigEndian(value, bytes = makeBytes(8)) {
+    const dataView = new DataView(bytes.buffer);
+    const valueLower32 = value & 0xffffffff;
+    dataView.setUint32(0, 0);
+    dataView.setUint32(4, valueLower32);
+    return bytes;
+}
+export function readUint64BigEndian(bytes) {
+    const dataView = new DataView(bytes.buffer);
+    return dataView.getUint32(4);
+}

package/dist/mjs/utils/url.js

@@ -0,0 +1,50 @@
+import { BeeArgumentError } from './error';
+import { isObject } from './type';
+function isNodeJsError(e) {
+    return isObject(e) && typeof e.code === 'string';
+}
+/**
+ * Validates that passed string is valid URL of Bee.
+ * We support only HTTP and HTTPS protocols.
+ *
+ * @param url
+ */
+export function isValidBeeUrl(url) {
+    try {
+        if (typeof url !== 'string') {
+            return false;
+        }
+        const urlObject = new URL(url);
+        // There can be wide range of protocols passed.
+        return urlObject.protocol === 'http:' || urlObject.protocol === 'https:';
+    }
+    catch (e) {
+        // URL constructor throws TypeError if not valid URL
+        // TODO: Drop the `.code` hack for NodeJS environment: https://github.com/ethersphere/bee-js/issues/204
+        if (e instanceof TypeError || (isNodeJsError(e) && e.code === 'ERR_INVALID_URL')) {
+            return false;
+        }
+        throw e;
+    }
+}
+/**
+ * Validates that passed string is valid URL of Bee, if not it throws BeeArgumentError.
+ * We support only HTTP and HTTPS protocols.
+ * @param url
+ * @throws BeeArgumentError if non valid URL
+ */
+export function assertBeeUrl(url) {
+    if (!isValidBeeUrl(url)) {
+        throw new BeeArgumentError('URL is not valid!', url);
+    }
+}
+/**
+ * Removes trailing slash out of the given string.
+ * @param url
+ */
+export function stripLastSlash(url) {
+    if (url.endsWith('/')) {
+        return url.slice(0, -1);
+    }
+    return url;
+}

package/dist/{src → types}/bee-debug.d.ts

@@ -1,4 +1,4 @@
-import type { Address, Peer, BalanceResponse, PeerBalance, ChequebookAddressResponse, ChequebookBalanceResponse, LastChequesResponse, LastChequesForPeerResponse, LastCashoutActionResponse, Settlements, AllSettlements, RemovePeerResponse, Topology, PingResponse, Health, NodeAddresses, ReserveState, ChainState, NumberString, ExtendedTag, PostageBatchBuckets, DebugPostageBatch, TransactionInfo, TransactionHash, NodeInfo } from './types';
+import type { Address, Peer, BalanceResponse, PeerBalance, ChequebookAddressResponse, ChequebookBalanceResponse, LastChequesResponse, LastChequesForPeerResponse, LastCashoutActionResponse, Settlements, AllSettlements, RemovePeerResponse, Topology, PingResponse, Health, NodeAddresses, ReserveState, ChainState, NumberString, ExtendedTag, PostageBatchBuckets, DebugPostageBatch, TransactionInfo, TransactionHash, NodeInfo, BeeVersions } from './types';
 import { BatchId, BeeOptions, CashoutOptions, PostageBatchOptions, RequestOptions, Tag } from './types';
 export declare class BeeDebug {
     /**
@@ -125,8 +125,54 @@ export declare class BeeDebug {
      * Connnects to a node and checks if it is a supported Bee version by the bee-js
      *
      * @returns true if the Bee node version is supported
+     * @deprecated Use `BeeDebug.isSupportedExactVersion()` instead
      */
     isSupportedVersion(options?: RequestOptions): Promise<boolean> | never;
+    /**
+     * Connects to a node and checks if its version matches with the one that bee-js supports.
+     *
+     * Be aware that this is the most strict version check and most probably
+     * you will want to use more relaxed API-versions based checks like
+     * `BeeDebug.isSupportedApiVersion()`, `BeeDebug.isSupportedMainApiVersion()` or `BeeDebug.isSupportedDebugApiVersion()`
+     * based on your use-case.
+     *
+     * @param options
+     */
+    isSupportedExactVersion(options?: RequestOptions): Promise<boolean> | never;
+    /**
+     * Connects to a node and checks if its main's API version matches with the one that bee-js supports.
+     *
+     * This is useful if you are not using `BeeDebug` class (for anything else then this check)
+     * and want to make sure about compatibility.
+     *
+     * @param options
+     */
+    isSupportedMainApiVersion(options?: RequestOptions): Promise<boolean> | never;
+    /**
+     * Connects to a node and checks if its Debug API version matches with the one that bee-js supports.
+     *
+     * This is useful if you are not using `Bee` class in your application and want to make sure
+     * about compatibility.
+     *
+     * @param options
+     */
+    isSupportedDebugApiVersion(options?: RequestOptions): Promise<boolean> | never;
+    /**
+     *
+     * Connects to a node and checks if its Main and Debug API versions matches with the one that bee-js supports.
+     *
+     * This should be the main way how to check compatibility for your app and Bee node.
+     *
+     * @param options
+     */
+    isSupportedApiVersion(options?: RequestOptions): Promise<boolean> | never;
+    /**
+     * 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
+     */
+    getVersions(options?: RequestOptions): Promise<BeeVersions> | never;
     /**
      * Get reserve state
      */