@ethersphere/bee-js 10.2.0 → 10.4.0

package/dist/types/bee.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
 import { Readable } from 'stream';
 import { Chunk } from './chunk/cac';
+import { SingleOwnerChunk } from './chunk/soc';
 import { FeedPayloadResult } from './modules/feed';
 import type { AllSettlements, BalanceResponse, BeeOptions, BeeRequestOptions, BeeVersions, ChainState, ChequebookAddressResponse, ChequebookBalanceResponse, CollectionUploadOptions, DebugStatus, DownloadOptions, EnvelopeWithBatchId, FeedReader, FeedWriter, FileData, FileUploadOptions, GetGranteesResult, GlobalPostageBatch, GranteesResult, GsocMessageHandler, GsocSubscription, Health, LastCashoutActionResponse, LastChequesForPeerResponse, LastChequesResponse, NodeAddresses, NodeInfo, NumberString, Peer, PeerBalance, Pin, PingResponse, PostageBatch, PostageBatchBuckets, PssMessageHandler, PssSubscription, Readiness, RedistributionState, RedundancyLevel, RedundantUploadOptions, ReferenceInformation, RemovePeerResponse, ReserveState, SOCReader, SOCWriter, Settlements, Tag, Topology, TransactionInfo, UploadOptions, WalletBalance } from './types';
 import { AllTagsOptions, Collection, PostageBatchOptions, TransactionOptions, UploadResult } from './types';
@@ -8,7 +9,7 @@ import { Bytes } from './utils/bytes';
 import { Duration } from './utils/duration';
 import { Size } from './utils/size';
 import { BZZ, DAI } from './utils/tokens';
-import { BatchId, EthAddress, FeedIndex, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Topic, TransactionId } from './utils/typed-bytes';
+import { BatchId, EthAddress, FeedIndex, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Span, Topic, TransactionId } from './utils/typed-bytes';
 import { UploadProgress } from './utils/upload-progress';
 /**
  * The main component that abstracts operations available on the Bee API.
@@ -123,7 +124,7 @@ export declare class Bee {
      * Chunks uploaded with this method should be retrieved with the {@link downloadChunk} method.
      *
      * @param stamp Postage Batch ID or an Envelope created with the {@link createEnvelope} method.
-     * @param data    Raw chunk to be uploaded
+     * @param data    Raw chunk to be uploaded (Content Addressed Chunk or Single Owner Chunk)
      * @param options Additional options like tag, encryption, pinning, content-type and request options
      * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
      *
@@ -131,7 +132,7 @@ export declare class Bee {
      * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
      * @see [Bee API reference - `POST /chunks`](https://docs.ethswarm.org/api/#tag/Chunk/paths/~1chunks/post)
      */
-    uploadChunk(stamp: EnvelopeWithBatchId | BatchId | Uint8Array | string, data: Uint8Array | Chunk, options?: UploadOptions, requestOptions?: BeeRequestOptions): Promise<UploadResult>;
+    uploadChunk(stamp: EnvelopeWithBatchId | BatchId | Uint8Array | string, data: Uint8Array | Chunk | SingleOwnerChunk, options?: UploadOptions, requestOptions?: BeeRequestOptions): Promise<UploadResult>;
     /**
      * Downloads a chunk as a `Uint8Array`.
      *
@@ -608,6 +609,60 @@ export declare class Bee {
      */
     makeFeedWriter(topic: Topic | Uint8Array | string, signer?: PrivateKey | Uint8Array | string, requestOptions?: BeeRequestOptions): FeedWriter;
     fetchLatestFeedUpdate(topic: Topic | Uint8Array | string, owner: EthAddress | Uint8Array | string, requestOptions?: BeeRequestOptions): Promise<FeedPayloadResult>;
+    /**
+     * Creates a Content Addressed Chunk.
+     *
+     * To be uploaded with the {@link uploadChunk} method.
+     *
+     * Payload size must be between 1 and 4096 bytes.
+     *
+     * @param rawPayload Data to be stored in the chunk. If the data is a string, it will be converted to UTF-8 bytes.
+     * @param span       Optional span for the chunk. If not provided, it will be set to the length of the payload.
+     *
+     * @example
+     *
+     */
+    makeContentAddressedChunk(rawPayload: Bytes | Uint8Array | string, span?: Span | bigint): Chunk;
+    /**
+     * Attempts to unmarshal arbitrary data into a Content Addressed Chunk.
+     * Throws an error if the data is not a valid CAC.
+     *
+     * @param data The chunk data (`span` and `payload`)
+     */
+    unmarshalContentAddressedChunk(data: Bytes | Uint8Array): Chunk;
+    /**
+     * Creates a Single Owner Chunk.
+     *
+     * To be uploaded with the {@link uploadChunk} method.
+     *
+     * Identical to chaining `makeContentAddressedChunk` and `toSingleOwnerChunk`.
+     *
+     * Payload size must be between 1 and 4096 bytes.
+     *
+     * @param address     Address of the Content Addressed Chunk
+     * @param span        Span of the Content Addressed Chunk
+     * @param payload     Payload of the Content Addressed Chunk
+     * @param identifier  The identifier of the chunk
+     * @param signer      The signer interface for signing the chunk
+     */
+    makeSingleOwnerChunk(address: Reference, span: Span, payload: Bytes, identifier: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string): SingleOwnerChunk;
+    /**
+     * Calculates the address of a Single Owner Chunk based on its identifier and owner address.
+     *
+     * @param identifier
+     * @param address
+     */
+    calculateSingleOwnerChunkAddress(identifier: Identifier, address: EthAddress): Reference;
+    /**
+     * Attempts to unmarshal arbitrary data into a Single Owner Chunk.
+     * Throws an error if the data is not a valid SOC.
+     *
+     * @param data    The chunk data
+     * @param address The address of the single owner chunk
+     *
+     * @returns a single owner chunk or throws error
+     */
+    unmarshalSingleOwnerChunk(data: Bytes | Uint8Array, address: Reference | Uint8Array | string): SingleOwnerChunk;
     /**
      * Returns an object for reading single owner chunks
      *

package/dist/types/chunk/cac.d.ts

@@ -1,26 +1,40 @@
 import { Bytes } from '../utils/bytes';
-import { Reference, Span } from '../utils/typed-bytes';
+import { Identifier, PrivateKey, Reference, Span } from '../utils/typed-bytes';
+import { SingleOwnerChunk } from './soc';
 export declare const MIN_PAYLOAD_SIZE = 1;
 export declare const MAX_PAYLOAD_SIZE = 4096;
 /**
- * General chunk interface for Swarm
+ * Content Addressed Chunk (CAC) is the immutable building block of Swarm,
+ * holding at most 4096 bytes of payload.
  *
- * It stores the serialized data and provides functions to access
- * the fields of a chunk.
+ * - `span` indicates the size of the `payload` in bytes.
+ * - `payload` contains the actual data or the body of the chunk.
+ * - `data` contains the full chunk data - `span` and `payload`.
+ * - `address` is the Swarm hash (or reference) of the chunk.
  *
- * It also provides an address function to calculate the address of
- * the chunk that is required for the Chunk API.
+ * The `toSingleOwnerChunk` method allows converting the CAC into a Single Owner Chunk (SOC).
  */
 export interface Chunk {
+    /**
+     * Contains the full chunk data - `span` + `payload`.
+     */
     readonly data: Uint8Array;
+    /**
+     * Indicates the size of the `payload` in bytes.
+     */
     span: Span;
+    /**
+     * Contains the actual data or the body of the chunk.
+     */
     payload: Bytes;
+    /**
+     * The Swarm hash (or reference) of the chunk.
+     */
     address: Reference;
+    /**
+     * Converts the CAC into a Single Owner Chunk (SOC).
+     */
+    toSingleOwnerChunk: (identifier: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string) => SingleOwnerChunk;
 }
-/**
- * Creates a content addressed chunk and verifies the payload size.
- *
- * @param payloadBytes the data to be stored in the chunk
- */
-export declare function makeContentAddressedChunk(payloadBytes: Uint8Array | string): Chunk;
-export declare function asContentAddressedChunk(chunkBytes: Uint8Array): Chunk;
+export declare function unmarshalContentAddressedChunk(data: Bytes | Uint8Array): Chunk;
+export declare function makeContentAddressedChunk(rawPayload: Bytes | Uint8Array | string, span?: Span | bigint): Chunk;

package/dist/types/chunk/soc.d.ts

@@ -1,29 +1,61 @@
 import { BeeRequestOptions, UploadOptions, UploadResult } from '../types';
 import { Bytes } from '../utils/bytes';
-import { BatchId, EthAddress, Identifier, PrivateKey, Reference, Signature } from '../utils/typed-bytes';
+import { BatchId, EthAddress, Identifier, PrivateKey, Reference, Signature, Span } from '../utils/typed-bytes';
 import { Chunk } from './cac';
 /**
- * With single owner chunks, a user can assign arbitrary data to an
- * address and attest chunk integrity with their digital signature.
+ * Single Owner Chunk (SOC) is a chunk type where the address is determined by the owner and an arbitrary identifier.
+ * Its integrity is attested by the owner's digital signature.
  *
- * This interface extends the Chunk interface so it has the same
- * properties, but the address calculation is based on the identifier
- * and the owner of the chunk.
+ * Similar to Content Addressed Chunks (CAC), SOCs have a maximum payload size of 4096 bytes.
+ *
+ * - `span` indicates the size of the `payload` in bytes.
+ * - `payload` contains the actual data or the body of the chunk.
+ * - `data` contains the full chunk data - `span` and `payload`.
+ * - `address` is the Swarm hash (or reference) of the chunk.
+ * - `identifier` is an arbitrary identifier selected by the uploader.
+ * - `signature` is the digital signature of the owner over the identifier and the underlying CAC address.
+ * - `owner` is the Ethereum address of the chunk owner.
  */
-export interface SingleOwnerChunk extends Chunk {
+export interface SingleOwnerChunk {
+    /**
+     * Contains the full chunk data - `span` + `payload`.
+     */
+    readonly data: Uint8Array;
+    /**
+     * Indicates the size of the `payload` in bytes.
+     */
+    span: Span;
+    /**
+     * Contains the actual data or the body of the chunk.
+     */
+    payload: Bytes;
+    /**
+     * The Swarm hash (or reference) of the chunk.
+     */
+    address: Reference;
+    /**
+     * An arbitrary identifier selected by the uploader.
+     */
     identifier: Identifier;
+    /**
+     * The digital signature of the owner over the identifier and the underlying CAC address.
+     */
     signature: Signature;
+    /**
+     * The Ethereum address of the chunk owner.
+     */
     owner: EthAddress;
 }
 /**
- * Verifies if the data is a valid single owner chunk
+ * Unmarshals arbitrary data into a Single Owner Chunk.
+ * Throws an error if the data is not a valid SOC.
  *
  * @param data    The chunk data
  * @param address The address of the single owner chunk
  *
  * @returns a single owner chunk or throws error
  */
-export declare function makeSingleOwnerChunkFromData(data: Bytes | Uint8Array, address: Reference | Uint8Array | string): SingleOwnerChunk;
+export declare function unmarshalSingleOwnerChunk(data: Bytes | Uint8Array, address: Reference | Uint8Array | string): SingleOwnerChunk;
 export declare function makeSOCAddress(identifier: Identifier, address: EthAddress): Reference;
 /**
  * Creates a single owner chunk object
@@ -32,7 +64,7 @@ export declare function makeSOCAddress(identifier: Identifier, address: EthAddre
  * @param identifier  The identifier of the chunk
  * @param signer      The signer interface for signing the chunk
  */
-export declare function makeSingleOwnerChunk(chunk: Chunk, identifier: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string): SingleOwnerChunk;
+export declare function makeSingleOwnerChunk(address: Reference, span: Span, payload: Bytes, identifier: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string): SingleOwnerChunk;
 /**
  * Helper function to upload a chunk.
  *
@@ -55,7 +87,7 @@ export declare function uploadSingleOwnerChunk(requestOptions: BeeRequestOptions
  * @param options
  */
 export declare function uploadSingleOwnerChunkData(requestOptions: BeeRequestOptions, signer: PrivateKey | Uint8Array | string, stamp: BatchId | Uint8Array | string, identifier: Identifier | Uint8Array | string, data: Uint8Array, options?: UploadOptions): Promise<UploadResult>;
-export declare function uploadSingleOwnerChunkWithWrappedChunk(requestOptions: BeeRequestOptions, signer: PrivateKey | Uint8Array | string, stamp: BatchId | Uint8Array | string, identifier: Identifier | Uint8Array | string, rootChunk: Uint8Array, options?: UploadOptions): Promise<UploadResult>;
+export declare function uploadSingleOwnerChunkWithWrappedChunk(requestOptions: BeeRequestOptions, signer: PrivateKey | Uint8Array | string, stamp: BatchId | Uint8Array | string, identifier: Identifier | Uint8Array | string, wrappedChunk: Chunk, options?: UploadOptions): Promise<UploadResult>;
 /**
  * Helper function to download SOC.
  *

package/dist/types/index.d.ts

@@ -2,6 +2,8 @@ import { Bee } from './bee';
 import { BeeDev } from './bee-dev';
 import { Stamper } from './stamper/stamper';
 export { MerkleTree } from 'cafe-utility';
+export type { Chunk } from './chunk/cac';
+export type { SingleOwnerChunk } from './chunk/soc';
 export { MantarayNode } from './manifest/manifest';
 export { SUPPORTED_BEE_VERSION, SUPPORTED_BEE_VERSION_EXACT } from './modules/debug/status';
 export * from './types';

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

@@ -2,4 +2,4 @@ export { getCollectionSize, makeCollectionFromFileList } from './collection';
 export { getFolderSize } from './collection.node';
 export { makeMaxTarget } from './pss';
 export { approximateOverheadForRedundancyLevel, getRedundancyStat, getRedundancyStats } from './redundancy';
-export { getAmountForDuration, getDepthForSize, getStampCost, getStampDuration, getStampEffectiveBytes, getStampEffectiveBytesBreakpoints, getStampTheoreticalBytes, getStampUsage, } from './stamps';
+export { getAmountForDuration, getDepthForSize, getStampCost, getStampDuration, getStampEffectiveBytes, getStampEffectiveBytesBreakpoints, getStampTheoreticalBytes, getStampUsage, mapPostageBatch, unmapPostageBatch, } from './stamps';

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

@@ -1,4 +1,4 @@
-import { EnvelopeWithBatchId, NumberString, RedundancyLevel } from '../types';
+import { EnvelopeWithBatchId, NumberString, PostageBatch, RedundancyLevel } from '../types';
 import { Bytes } from './bytes';
 import { Duration } from './duration';
 import { Size } from './size';
@@ -58,3 +58,17 @@ export declare function getAmountForDuration(duration: Duration, pricePerBlock:
 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;
+export interface RawPostageBatch {
+    batchID: string;
+    utilization: number;
+    usable: boolean;
+    label: string;
+    depth: number;
+    amount: string;
+    bucketDepth: number;
+    blockNumber: number;
+    immutableFlag: boolean;
+    batchTTL: number;
+}
+export declare function mapPostageBatch(raw: RawPostageBatch, encryption?: boolean, erasureCodeLevel?: RedundancyLevel): PostageBatch;
+export declare function unmapPostageBatch(batch: PostageBatch): RawPostageBatch;

package/package.json

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