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

package/dist/mjs/utils/type.js

@@ -0,0 +1,336 @@
+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/index.js";
+import { BeeArgumentError } from "./error.js";
+import { isFile } from "./file.js";
+import { assertHexString, assertPrefixedHexString } from "./hex.js";
+import { isReadable } from "./stream.js";
+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.js"; // 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,57 @@
+import { BeeArgumentError } from "./error.js";
+import { isObject } from "./type.js";
+
+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
      */

package/dist/types/modules/debug/status.d.ts

@@ -0,0 +1,72 @@
+import type { Health, NodeInfo } from '../../types/debug';
+import { Ky } from '../../types';
+import { BeeVersions } from '../../types/debug';
+export declare const SUPPORTED_BEE_VERSION_EXACT = "1.4.3-1213e063";
+export declare const SUPPORTED_API_VERSION = "2.0.0";
+export declare const SUPPORTED_DEBUG_API_VERSION = "1.2.1";
+export declare const SUPPORTED_BEE_VERSION: string;
+/**
+ * Get health of node
+ *
+ * @param ky Ky debug instance
+ */
+export declare function getHealth(ky: Ky): Promise<Health>;
+/**
+ * Get information about Bee node
+ *
+ * @param ky Ky debug instance
+ */
+export declare function getNodeInfo(ky: Ky): Promise<NodeInfo>;
+/**
+ * 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 declare function isSupportedVersion(ky: Ky): Promise<boolean>;
+/**
+ * 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 declare function isSupportedExactVersion(ky: Ky): Promise<boolean>;
+/**
+ * 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 declare function isSupportedMainApiVersion(ky: Ky): Promise<boolean>;
+/**
+ * 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 declare function isSupportedDebugApiVersion(ky: Ky): Promise<boolean>;
+/**
+ * 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 declare function isSupportedApiVersion(ky: Ky): Promise<boolean>;
+/**
+ * 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 declare function getVersions(ky: Ky): Promise<BeeVersions>;

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

@@ -121,6 +121,14 @@ export interface Health {
     apiVersion: string;
     debugApiVersion: string;
 }
+export interface BeeVersions {
+    supportedBeeVersion: string;
+    supportedBeeApiVersion: string;
+    supportedBeeDebugApiVersion: string;
+    beeVersion: string;
+    beeApiVersion: string;
+    beeDebugApiVersion: string;
+}
 export declare enum BeeModes {
     FULL = "full",
     LIGHT = "light",

package/dist/{src → types}/types/index.d.ts

@@ -10,8 +10,8 @@ import type { HexString } from '../utils/hex';
 import type ky from 'ky-universal';
 import type { Readable as NativeReadable } from 'stream';
 import type { Readable as CompatibilityReadable } from 'readable-stream';
-import type { ReadableStream as ReadableStreamPonyfill } from 'web-streams-polyfill/ponyfill';
-import { Options as KyOptions } from 'ky-universal';
+import type { ReadableStream as ReadableStreamPonyfill } from 'web-streams-polyfill';
+import { Options as KyOptions } from './ky-options';
 export * from './debug';
 export declare type Ky = typeof ky;
 export interface Dictionary<T> {
@@ -362,6 +362,7 @@ export interface FeedWriter extends FeedReader {
  * Interface for downloading single owner chunks
  */
 export interface SOCReader {
+    readonly owner: HexEthAddress;
     /**
      * Downloads a single owner chunk
      *