@ethersphere/bee-js 2.1.1 → 3.3.0

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

@@ -1,7 +1,7 @@
 import { FeedType } from './feed/type';
 import { EthAddress } from './utils/eth';
-import { AllTagsOptions, Collection, NumberString, PostageBatchOptions, Readable, RequestOptions, UploadResult } from './types';
-import type { Tag, FileData, Reference, UploadOptions, PublicKey, AddressPrefix, PssMessageHandler, PssSubscription, CollectionUploadOptions, FileUploadOptions, Data, Signer, FeedReader, FeedWriter, SOCWriter, SOCReader, Topic, BeeOptions, JsonFeedOptions, AnyJson, Pin, PostageBatch, BatchId } from './types';
+import { AllTagsOptions, Collection, Readable, RequestOptions, UploadResult } from './types';
+import type { Tag, FileData, Reference, UploadOptions, PublicKey, AddressPrefix, PssMessageHandler, PssSubscription, CollectionUploadOptions, FileUploadOptions, Data, Signer, FeedReader, FeedWriter, SOCWriter, SOCReader, Topic, BeeOptions, JsonFeedOptions, AnyJson, Pin, BatchId } from './types';
 /**
  * The main component that abstracts operations available on the main Bee API.
  *
@@ -57,6 +57,27 @@ export declare class Bee {
      * @see [Bee API reference - `GET /bytes`](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes~1{reference}/get)
      */
     downloadReadableData(reference: Reference | string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Upload chunk to a Bee node
+     *
+     * @param postageBatchId Postage BatchId to be used to upload the chunk with
+     * @param data    Raw chunk to be uploaded
+     * @param options Additional options like tag, encryption, pinning, content-type and request options
+     *
+     * @returns reference is a content hash of the data
+     * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/access-the-swarm/upload-and-download)
+     * @see [Bee API reference - `POST /chunks`](https://docs.ethswarm.org/api/#tag/Chunk/paths/~1chunks/post)
+     */
+    uploadChunk(postageBatchId: string | BatchId, data: Uint8Array, options?: UploadOptions): Promise<Reference>;
+    /**
+     * Download chunk as a byte array
+     *
+     * @param reference Bee chunk reference
+     * @param options Options that affects the request behavior
+     * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/access-the-swarm/upload-and-download)
+     * @see [Bee API reference - `GET /chunks`](https://docs.ethswarm.org/api/#tag/Chunk/paths/~1chunks~1{reference}/get)
+     */
+    downloadChunk(reference: Reference | string, options?: RequestOptions): Promise<Data>;
     /**
      * Upload single file to a Bee node.
      *
@@ -448,50 +469,6 @@ export declare class Bee {
      * @see [Bee docs - Chunk Types](https://docs.ethswarm.org/docs/dapps-on-swarm/chunk-types#single-owner-chunks)
      */
     makeSOCWriter(signer?: Signer | Uint8Array | string, options?: RequestOptions): SOCWriter;
-    /**
-     * Creates new postage batch from the funds that the node has available in its Ethereum account.
-     *
-     * 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/access-the-swarm/keep-your-data-alive).
-     *
-     * **WARNING: THIS CREATES TRANSACTIONS THAT SPENDS MONEY**
-     * **Warning! Not allowed when node is in Gateway mode!**
-     *
-     * @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 options Options for creation of postage batch and request options
-     * @throws BeeArgumentError when negative amount or depth is specified
-     * @throws TypeError if non-integer value is passed to amount or depth
-     *
-     * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
-     * @see [Bee API reference - `POST /stamps`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps~1{amount}~1{depth}/post)
-     * @deprecated Use DebugBee for postage batch management
-     */
-    createPostageBatch(amount: NumberString, depth: number, options?: PostageBatchOptions): Promise<BatchId>;
-    /**
-     * Return details for specific postage batch.
-     *
-     * **Warning! Not allowed when node is in Gateway mode!**
-     *
-     * @param postageBatchId Batch ID
-     * @param options Options that affects the request behavior
-     *
-     * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
-     * @see [Bee API reference - `GET /stamps/${id}`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps~1{id}/get)
-     * @deprecated Use DebugBee for postage batch management
-     */
-    getPostageBatch(postageBatchId: BatchId | string, options?: RequestOptions): Promise<PostageBatch>;
-    /**
-     * Return all postage batches that has the node available.
-     *
-     * **Warning! Not allowed when node is in Gateway mode!**
-     *
-     * @param options Options that affects the request behavior
-     * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive)
-     * @see [Bee API reference - `GET /stamps`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps/get)
-     * @deprecated Use DebugBee for postage batch management
-     */
-    getAllPostageBatch(options?: RequestOptions): Promise<PostageBatch[]>;
     /**
      * Ping the Bee node to see if there is a live Bee node on the given URL.
      *

package/dist/{src → types}/modules/chunk.d.ts

@@ -1,5 +1,4 @@
-import type { BatchId, Ky, UploadOptions } from '../types';
-import { Reference } from '../types';
+import type { BatchId, Data, Ky, Reference, UploadOptions } from '../types';
 /**
  * Upload chunk to a Bee node
  *
@@ -20,11 +19,4 @@ export declare function upload(ky: Ky, data: Uint8Array, postageBatchId: BatchId
  * @param hash Bee content reference
  *
  */
-export declare function download(ky: Ky, hash: string): Promise<Uint8Array>;
-/**
- * Download chunk data as a readable stream
- *
- * @param ky Ky instance for given Bee class instance
- * @param hash Bee content reference
- */
-export declare function downloadReadable(ky: Ky, hash: string): Promise<ReadableStream<Uint8Array>>;
+export declare function download(ky: Ky, hash: string): Promise<Data>;

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

@@ -118,7 +118,34 @@ export interface BalanceResponse {
 export interface Health {
     status: 'ok';
     version: string;
+    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",
+    DEV = "dev"
 }
+/**
+ * Information about Bee node and its configuration
+ */
+export interface NodeInfo {
+    gatewayMode: boolean;
+    beeMode: BeeModes;
+}
+/**
+ * Information about Bee node and its configuration
+ * @deprecated Use NodeInfo instead
+ */
+export declare type NodesInfo = NodeInfo;
 export interface RemovePeerResponse {
     message: string;
     code: 0;

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

@@ -11,11 +11,16 @@ 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';
 export * from './debug';
 export declare type Ky = typeof ky;
 export interface Dictionary<T> {
     [Key: string]: T;
 }
+export declare const SPAN_SIZE = 8;
+export declare const SECTION_SIZE = 32;
+export declare const BRANCHES = 128;
+export declare const CHUNK_SIZE: number;
 export declare const ADDRESS_HEX_LENGTH = 64;
 export declare const PSS_TARGET_HEX_LENGTH_MAX = 6;
 export declare const PUBKEY_HEX_LENGTH = 66;
@@ -59,6 +64,17 @@ export declare type BatchId = HexString<typeof BATCH_ID_HEX_LENGTH>;
  * It represents PSS Address Prefix that is used to define address neighborhood that will receive the PSS message.
  */
 export declare type AddressPrefix = HexString;
+/**
+ * Internal interface that represents configuration for creating a request with Ky
+ */
+export interface KyRequestOptions extends Omit<KyOptions, 'searchParams'> {
+    path: string;
+    responseType?: 'json' | 'arraybuffer' | 'stream';
+    /**
+     * Overridden parameter that allows undefined as a value.
+     */
+    searchParams?: Record<string, string | number | boolean | undefined>;
+}
 export interface RequestOptions {
     /**
      * Timeout of requests in milliseconds
@@ -138,6 +154,17 @@ export interface UploadOptions extends RequestOptions {
      * @link Tag
      */
     tag?: number;
+    /**
+     * Determines if the uploaded data should be sent to the network immediately (eq. deferred=false) or in a deferred fashion (eq. deferred=true).
+     *
+     * With deferred style client uploads all the data to Bee node first and only then Bee node starts push the data to network itself. The progress of this upload can be tracked with tags.
+     * With non-deferred style client uploads the data to Bee which immediately starts pushing the data to network. The request is only finished once all the data was pushed through the Bee node to the network.
+     *
+     * In future there will be move to the non-deferred style and even the support for deferred upload will be removed from Bee itself.
+     *
+     * @default true
+     */
+    deferred?: boolean;
 }
 export interface FileUploadOptions extends UploadOptions {
     /**
@@ -335,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
      *
@@ -368,14 +396,16 @@ export interface PostageBatch {
     bucketDepth: number;
     blockNumber: number;
     immutableFlag: boolean;
-}
-export interface DebugPostageBatch extends PostageBatch {
     /**
      * The time (in seconds) remaining until the batch expires; -1 signals that the batch never expires; 0 signals that the batch has already expired.
      */
     batchTTL: number;
     exists: boolean;
 }
+/**
+ * @deprecated Use PostageBatch instead.
+ */
+export declare type DebugPostageBatch = PostageBatch;
 export interface BatchBucket {
     bucketID: number;
     collisions: number;

package/dist/types/utils/collection.browser.d.ts

@@ -0,0 +1,15 @@
+import { Collection } from '../types';
+/**
+ * Creates array in the format of Collection with data loaded from directory on filesystem.
+ * The function loads all the data into memory!
+ *
+ * @param dir path to the directory
+ */
+export declare function makeCollectionFromFS(dir: string): Promise<Collection<Uint8Array>>;
+/**
+ * Calculate folder size recursively
+ *
+ * @param dir the path to the folder to check
+ * @returns size in bytes
+ */
+export declare function getFolderSize(dir: string): Promise<number>;

package/dist/{src → types}/utils/collection.d.ts

@@ -1,13 +1,6 @@
 import { Collection } from '../types';
 export declare function isCollection(data: unknown): data is Collection<Uint8Array>;
 export declare function assertCollection(data: unknown): asserts data is Collection<Uint8Array>;
-/**
- * Creates array in the format of Collection with data loaded from directory on filesystem.
- * The function loads all the data into memory!
- *
- * @param dir path to the directory
- */
-export declare function makeCollectionFromFS(dir: string): Promise<Collection<Uint8Array>>;
 export declare function makeCollectionFromFileList(fileList: FileList | File[]): Promise<Collection<Uint8Array>>;
 /**
  * Calculate cumulative size of files
@@ -16,10 +9,3 @@ export declare function makeCollectionFromFileList(fileList: FileList | File[]):
  * @returns size in bytes
  */
 export declare function getCollectionSize(fileList: FileList | File[]): number;
-/**
- * Calculate folder size recursively
- *
- * @param dir the path to the folder to check
- * @returns size in bytes
- */
-export declare function getFolderSize(dir: string): Promise<number>;

package/dist/types/utils/collection.node.d.ts

@@ -0,0 +1,15 @@
+import { Collection } from '../types';
+/**
+ * Creates array in the format of Collection with data loaded from directory on filesystem.
+ * The function loads all the data into memory!
+ *
+ * @param dir path to the directory
+ */
+export declare function makeCollectionFromFS(dir: string): Promise<Collection<Uint8Array>>;
+/**
+ * Calculate folder size recursively
+ *
+ * @param dir the path to the folder to check
+ * @returns size in bytes
+ */
+export declare function getFolderSize(dir: string): Promise<number>;

package/dist/types/utils/error.d.ts

@@ -0,0 +1,33 @@
+import { KyRequestOptions } from '../types';
+export declare class BeeError extends Error {
+    constructor(message: string);
+}
+export declare class BeeArgumentError extends BeeError {
+    readonly value: unknown;
+    constructor(message: string, value: unknown);
+}
+export declare class BeeRequestError extends BeeError {
+    readonly requestOptions: KyRequestOptions;
+    /**
+     * @param message
+     * @param requestOptions KyOptions that were used to assemble the request. THIS MIGHT NOT BE COMPLETE! If custom Ky instance was used that has set defaults then these defaults are not visible in this object!
+     */
+    constructor(message: string, requestOptions: KyRequestOptions);
+}
+export declare class BeeResponseError extends BeeError {
+    readonly status: number;
+    readonly response: Response;
+    readonly responseBody: string;
+    readonly requestOptions: KyRequestOptions;
+    /**
+     * @param status HTTP status code number
+     * @param response Response returned from the server
+     * @param responseBody Response body as string which is returned from response.text() call
+     * @param requestOptions KyOptions that were used to assemble the request. THIS MIGHT NOT BE COMPLETE! If custom Ky instance was used that has set defaults then these defaults are not visible in this object!
+     * @param message
+     */
+    constructor(status: number, response: Response, responseBody: string, requestOptions: KyRequestOptions, message: string);
+}
+export declare class BeeNotAJsonError extends BeeError {
+    constructor();
+}

package/dist/{src → types}/utils/expose.d.ts

@@ -1,7 +1,9 @@
-export { getCollectionSize, getFolderSize } from './collection';
+export { getCollectionSize } from './collection';
+export { getFolderSize } from './collection.node';
 export { Bytes, FlexBytes, isBytes, assertBytes, isFlexBytes, assertFlexBytes, bytesAtOffset, flexBytesAtOffset, bytesEqual, } from './bytes';
 export { HexString, PrefixedHexString, makeHexString, hexToBytes, bytesToHex, intToHex, isHexString, assertHexString, assertPrefixedHexString, } from './hex';
 export { EthAddress, makeEthAddress, makeHexEthAddress, isHexEthAddress, ethToSwarmAddress, toLittleEndian, fromLittleEndian, makeEthereumWalletSigner, } from './eth';
 export { readableWebToNode, readableNodeToWeb, isReadableStream, isNodeReadable, normalizeToReadableStream, isReadable, } from './stream';
 export { keccak256Hash } from './hash';
 export { makeMaxTarget } from './pss';
+export { getStampUsage } from './stamps';

package/dist/{src → types}/utils/http.d.ts

@@ -1,13 +1,6 @@
 import type { BeeRequest, BeeResponse, HookCallback, Ky } from '../types';
 import { Options as KyOptions } from 'ky-universal';
-interface HttpOptions extends Omit<KyOptions, 'searchParams'> {
-    path: string;
-    responseType?: 'json' | 'arraybuffer' | 'stream';
-    /**
-     * Overridden parameter that allows undefined as a value.
-     */
-    searchParams?: Record<string, string | number | boolean | undefined>;
-}
+import { KyRequestOptions } from '../types';
 interface KyResponse<T> extends Response {
     data: T;
 }
@@ -20,6 +13,11 @@ export declare function wrapResponseClosure(cb: HookCallback<BeeResponse>): (req
  * @param obj
  */
 export declare function filterHeaders(obj?: object): Record<string, string> | undefined;
-export declare function http<T>(ky: Ky, config: HttpOptions): Promise<KyResponse<T>>;
+/**
+ * Main utility function to make HTTP requests.
+ * @param ky
+ * @param config
+ */
+export declare function http<T>(ky: Ky, config: KyRequestOptions): Promise<KyResponse<T>>;
 export declare function makeDefaultKy(kyConfig: KyOptions): Ky;
 export {};

package/dist/types/utils/stamps.d.ts

@@ -0,0 +1,12 @@
+import { DebugPostageBatch } from '../types';
+/**
+ * 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 declare function getStampUsage({ utilization, depth, bucketDepth }: DebugPostageBatch): number;

package/dist/{src → types}/utils/type.d.ts

@@ -12,6 +12,12 @@ export declare function isObject(value: unknown): value is Record<string, unknow
  * @param value
  */
 export declare function isStrictlyObject(value: unknown): value is object;
+/**
+ * Asserts if object is Error
+ *
+ * @param e
+ */
+export declare function isError(e: unknown): e is Error;
 export declare function assertStrictlyObject(value: unknown, name?: string): asserts value is object;
 export declare function assertBoolean(value: unknown, name?: string): asserts value is boolean;
 export declare function assertInteger(value: unknown, name?: string): asserts value is number | NumberString;