@ethersphere/bee-js 9.8.0 → 10.0.0

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

@@ -23,7 +23,7 @@ export interface Peer {
     fullNode?: boolean;
 }
 export interface ChequebookAddressResponse {
-    chequebookAddress: string;
+    chequebookAddress: EthAddress;
 }
 export interface ChequebookBalanceResponse {
     totalBalance: BZZ;

package/dist/types/types/index.d.ts

@@ -13,16 +13,24 @@ export declare const BRANCHES = 128;
 export declare const CHUNK_SIZE: number;
 export declare const PSS_TARGET_HEX_LENGTH_MAX = 4;
 /**
- * Minimal depth that can be used for creation of postage batch
+ * Minimum postage batch depth.
  */
 export declare const STAMPS_DEPTH_MIN = 17;
 /**
- * Maximal depth that can be used for creation of postage batch
+ * Maximum postage batch depth.
  */
 export declare const STAMPS_DEPTH_MAX = 255;
+/**
+ * Minimum tags API page size.
+ */
 export declare const TAGS_LIMIT_MIN = 1;
+/**
+ * Maximum tags API page size.
+ */
 export declare const TAGS_LIMIT_MAX = 1000;
-export declare const FEED_INDEX_HEX_LENGTH = 16;
+/**
+ * Behavior of the HTTP client, such as `timeout`, additional `headers`, custom `httpAgent`, etc.
+ */
 export type BeeRequestOptions = {
     baseURL?: string;
     timeout?: number;
@@ -32,13 +40,29 @@ export type BeeRequestOptions = {
     httpsAgent?: unknown;
     endlesslyRetry?: boolean;
 };
+/**
+ * Options for the Bee client which affect all method calls *(unless overridden in the method call itself)*.
+ *
+ * Extends `BeeRequestOptions`, which allows configuring the HTTP client behavior,
+ * such as `timeout`, additional `headers`, custom `httpAgent`, etc.
+ */
 export interface BeeOptions extends BeeRequestOptions {
     /**
-     * Signer object or private key of the Signer in form of either hex string or Uint8Array that will be default signer for the instance.
+     * Default signer (a private key) used for signing.
+     *
+     * Mainly used in single-owner chunk (SOC) related operations, and consequently in feeds.
+     *
+     * If not provided, methods such as `makeFeedWriter` and `makeSOCWriter`
+     * must be provided with a private key in their respective function calls.
      */
     signer?: PrivateKey | Uint8Array | string;
     /**
-     * Default gnosis when unspecified.
+     * Network on which the Bee node is running.
+     *
+     * This is currently used to determine block time for postage batch time-to-live (TTL) calculations.
+     * The block time for `gnosis` is `5` seconds, and for `sepolia` it is `15` seconds.
+     *
+     * Default value is `gnosis`.
      */
     network?: 'gnosis' | 'sepolia';
 }
@@ -146,14 +170,20 @@ export declare enum RedundancyStrategy {
 export interface DownloadOptions {
     /**
      * Specify the retrieve strategy on redundant data.
+     *
+     * Only applicable for erasure coded data.
      */
     redundancyStrategy?: RedundancyStrategy;
     /**
      * Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.
+     *
+     * Only applicable for erasure coded data.
      */
     fallback?: boolean;
     /**
      * Specify the timeout for chunk retrieval. The default is 30 seconds.
+     *
+     * This is not the timeout for the whole download operation, but rather for each chunk retrieval.
      */
     timeoutMs?: number;
     actPublisher?: PublicKey | Uint8Array | string;
@@ -200,7 +230,11 @@ export interface UploadHeaders {
     'swarm-postage-batch-id'?: string;
 }
 /**
- * Object that contains infromation about progress of upload of data to network.
+ * Object that contains information about upload progress of data to network.
+ *
+ * The total amount of chunks is represented by `split` property.
+ *
+ * The actual progress of the upload can be tracked by the `seen + synced` properties.
  *
  * @see [Bee docs - Syncing / Tags](https://docs.ethswarm.org/docs/develop/access-the-swarm/syncing)
  */
@@ -273,6 +307,7 @@ export interface PssSubscription {
 export interface PssMessageHandler {
     onMessage: (message: Bytes, subscription: PssSubscription) => void;
     onError: (error: BeeError, subscription: PssSubscription) => void;
+    onClose: (subscription: PssSubscription) => void;
 }
 export interface GsocSubscription {
     readonly address: EthAddress;
@@ -281,6 +316,7 @@ export interface GsocSubscription {
 export interface GsocMessageHandler {
     onMessage: (message: Bytes, subscription: GsocSubscription) => void;
     onError: (error: BeeError, subscription: GsocSubscription) => void;
+    onClose: (subscription: GsocSubscription) => void;
 }
 export interface ReferenceResponse {
     reference: Reference;
@@ -484,3 +520,69 @@ export interface EnvelopeWithBatchId extends Envelope {
 export type NumberString = string & {
     __numberString: never;
 };
+export declare const capacityBreakpoints: {
+    ENCRYPTION_OFF: {
+        0: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+        1: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+        2: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+        3: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+        4: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+    };
+    ENCRYPTION_ON: {
+        0: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+        1: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+        2: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+        3: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+        4: {
+            theoreticalVolume: string;
+            effectiveVolume: string;
+            batchDepth: number;
+            utilizationRate: string;
+        }[];
+    };
+};

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

@@ -16,3 +16,4 @@ export declare class Bytes {
     equals(other: Bytes | Uint8Array | string): boolean;
     represent(): string;
 }
+export declare function parseSizeToBytes(sizeStr: string): number;

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

@@ -1,5 +1,6 @@
 export declare class Duration {
     private seconds;
+    static ZERO: Duration;
     private constructor();
     static fromMilliseconds(milliseconds: number): Duration;
     static fromSeconds(seconds: number): Duration;
@@ -15,4 +16,5 @@ export declare class Duration {
     toYears(): number;
     toEndDate(startDate?: Date): Date;
     represent(): string;
+    isZero(): boolean;
 }

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

@@ -1,4 +1,4 @@
-import { EnvelopeWithBatchId, NumberString } from '../types';
+import { EnvelopeWithBatchId, NumberString, RedundancyLevel } from '../types';
 import { Bytes } from './bytes';
 import { Duration } from './duration';
 import { Size } from './size';
@@ -27,8 +27,8 @@ export declare function getStampTheoreticalBytes(depth: number): number;
  *
  * @returns {number} The effective size of the postage batch in bytes.
  */
-export declare function getStampEffectiveBytes(depth: number): number;
-export declare function getStampEffectiveBytesBreakpoints(): Map<number, number>;
+export declare function getStampEffectiveBytes(depth: number, encryption?: boolean, erasureCodeLevel?: RedundancyLevel): number;
+export declare function getStampEffectiveBytesBreakpoints(encryption: boolean, erasureCodeLevel?: RedundancyLevel): Map<number, number>;
 /**
  * Utility function that calculates the cost of a postage batch based on its depth and amount.
  */
@@ -55,6 +55,6 @@ export declare function getAmountForDuration(duration: Duration, pricePerBlock:
  * @param size The effective size of the postage batch
  * @returns
  */
-export declare function getDepthForSize(size: Size): number;
+export declare function getDepthForSize(size: Size, encryption?: boolean, erasureCodeLevel?: RedundancyLevel): number;
 export declare function convertEnvelopeToMarshaledStamp(envelope: EnvelopeWithBatchId): Bytes;
 export declare function marshalStamp(signature: Uint8Array, batchId: Uint8Array, timestamp: Uint8Array, index: Uint8Array): Bytes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethersphere/bee-js",
-  "version": "9.8.0",
+  "version": "10.0.0",
   "description": "Javascript client for Bee",
   "keywords": [
     "bee",