@upcoming/bee-js 9.9.1 → 10.1.2

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

@@ -1,8 +1,8 @@
-import type { BeeRequestOptions, GlobalPostageBatch, NumberString, PostageBatch, PostageBatchBuckets, PostageBatchOptions } from '../../types';
+import type { BeeRequestOptions, GlobalPostageBatch, NumberString, PostageBatch, PostageBatchBuckets, PostageBatchOptions, RedundancyLevel } from '../../types';
 import { BatchId } from '../../utils/typed-bytes';
 export declare function getGlobalPostageBatches(requestOptions: BeeRequestOptions): Promise<GlobalPostageBatch[]>;
 export declare function getAllPostageBatches(requestOptions: BeeRequestOptions): Promise<PostageBatch[]>;
-export declare function getPostageBatch(requestOptions: BeeRequestOptions, postageBatchId: BatchId): Promise<PostageBatch>;
+export declare function getPostageBatch(requestOptions: BeeRequestOptions, postageBatchId: BatchId, encryption?: boolean, erasureCodeLevel?: RedundancyLevel): Promise<PostageBatch>;
 export declare function getPostageBatchBuckets(requestOptions: BeeRequestOptions, postageBatchId: BatchId): Promise<PostageBatchBuckets>;
 export declare function createPostageBatch(requestOptions: BeeRequestOptions, amount: NumberString, depth: number, options?: PostageBatchOptions): Promise<BatchId>;
 export declare function topUpBatch(requestOptions: BeeRequestOptions, id: BatchId, amount: NumberString): Promise<BatchId>;

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;
@@ -414,6 +450,16 @@ export interface PostageBatch {
      * Theoretical size in bytes
      */
     theoreticalSize: Size;
+    /**
+     * Calculates the effective size of data that can be uploaded with this postage batch
+     * based on whether encryption is used and the desired redundancy level.
+     */
+    calculateSize(encryption: boolean, redundancyLevel: RedundancyLevel): Size;
+    /**
+     * Calculates the remaining size of data that can be uploaded with this postage batch
+     * based on whether encryption is used and the desired redundancy level.
+     */
+    calculateRemainingSize(encryption: boolean, redundancyLevel: RedundancyLevel): Size;
 }
 export interface BatchBucket {
     bucketID: number;

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

@@ -9,6 +9,30 @@ export declare class Duration {
     static fromWeeks(weeks: number): Duration;
     static fromYears(years: number): Duration;
     static fromEndDate(endDate: Date, startDate?: Date): Duration;
+    /**
+     * Parses a duration string and returns a `Duration` instance.
+     *
+     * Case insensitive. E.g. both `"28h"` and `"1D"` are valid.
+     *
+     * Whitespaces are ignored. E.g. both `"5 d"` and `"2weeks"` are valid.
+     *
+     * Decimal numbers are supported. E.g. `"1.5h"` is valid.
+     *
+     * Supported units:
+     *
+     * - ms, milli, millis, millisecond, milliseconds
+     * - s, sec, second, seconds
+     * - m, min, minute, minutes
+     * - h, hour, hours
+     * - d, day, days
+     * - w, week, weeks
+     * - month, months
+     * - y, year, years
+     *
+     * @param duration - A string representing a duration
+     * @returns a `Duration` instance
+     */
+    static parseFromString(duration: string): Duration;
     toSeconds(): number;
     toHours(): number;
     toDays(): number;

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

@@ -12,6 +12,29 @@ export declare class Size {
     static fromKilobytes(kilobytes: number): Size;
     static fromMegabytes(megabytes: number): Size;
     static fromGigabytes(gigabytes: number): Size;
+    /**
+     * Parses a size string and returns a `Size` instance.
+     *
+     * Case insensitive. E.g. both `"28MB"` and `"1gb"` are valid.
+     *
+     * Whitespaces are ignored. E.g. both `"512 kb"` and `"2megabytes"` are valid.
+     *
+     * Decimal numbers are supported. E.g. `"1.5gb"` is valid.
+     *
+     * Uses 1000 as the base for conversions. E.g. 1kb = 1000 bytes.
+     * This is consistent with the effective stamp utilization table.
+     *
+     * Supported units:
+     * - b, byte, bytes
+     * - kb, kilobyte, kilobytes
+     * - mb, megabyte, megabytes
+     * - gb, gigabyte, gigabytes
+     * - tb, terabyte, terabytes
+     *
+     * @param size - A string representing a size
+     * @returns a `Size` instance
+     */
+    static parseFromString(size: string): Size;
     toBytes(): number;
     toGigabytes(): number;
     toFormattedString(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upcoming/bee-js",
-  "version": "9.9.1",
+  "version": "10.1.2",
   "description": "Javascript client for Bee",
   "keywords": [
     "bee",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "axios": "^0.30.0",
-    "cafe-utility": "^31.0.0",
+    "cafe-utility": "^32.2.0",
     "debug": "^4.4.1",
     "isomorphic-ws": "^4.0.1",
     "semver": "^7.3.5",