Class: Bee

The main component that abstracts operations available on the main Bee API.

Not all methods are always available as it depends in what mode is Bee node launched in. For example gateway mode and light node mode has only limited set of endpoints enabled.

Constructors

constructor

• new Bee(url, options?)

Parameters

Name	Type	Description
url	string	URL on which is the main API of Bee node exposed
options?	BeeOptions

Defined in

bee-js/src/bee.ts:114

Properties

signer

• Optional Readonly signer: Signer

Default Signer object used for signing operations, mainly Feeds.

Defined in

bee-js/src/bee.ts:102

---

url

• Readonly url: string

URL on which is the main API of Bee node exposed

Defined in

bee-js/src/bee.ts:97

Methods

checkConnection

▸ checkConnection(options?): Promise<void>

Ping the Bee node to see if there is a live Bee node on the given URL.

throws If connection was not successful throw error

Parameters

Name	Type	Description
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<void>

Defined in

bee-js/src/bee.ts:1101

---

createFeedManifest

▸ createFeedManifest(postageBatchId, type, topic, owner, options?): Promise<Reference>

Create feed manifest chunk and return the reference to it.

Feed manifest chunk allows for a feed to be able to be resolved through /bzz endpoint.

see Bee docs - Feeds

see Bee API reference - POST /feeds TODO: Once breaking add support for Feed CID

Parameters

Name	Type	Description
postageBatchId	string | BatchId	Postage BatchId to be used to create the Feed Manifest
type	"sequence" | "epoch"	The type of the feed, can be 'epoch' or 'sequence'
topic	string | Uint8Array | Topic	Topic in hex or bytes
owner	string | Uint8Array | EthAddress	Owner's ethereum address in hex or bytes
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<Reference>

Defined in

bee-js/src/bee.ts:897

---

createTag

▸ createTag(options?): Promise<Tag>

Create a new Tag which is meant for tracking progres of syncing data across network.

Warning! Not allowed when node is in Gateway mode!

see Bee docs - Syncing / Tags

see Bee API reference - POST /tags

Parameters

Name	Type	Description
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<Tag>

Defined in

bee-js/src/bee.ts:462

---

deleteTag

▸ deleteTag(tagUid, options?): Promise<void>

Delete Tag

Warning! Not allowed when node is in Gateway mode!

throws TypeError if tagUid is in not correct format

throws BeeResponse error if something went wrong on the Bee node side while deleting the tag.

see Bee docs - Syncing / Tags

see Bee API reference - DELETE /tags/{uid}

Parameters

Name	Type	Description
tagUid	number | Tag	UID or tag object to be retrieved
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<void>

Defined in

bee-js/src/bee.ts:523

---

downloadChunk

▸ downloadChunk(reference, options?): Promise<Data>

Download chunk as a byte array

throws TypeError if some of the input parameters is not expected type

throws BeeArgumentError if there is passed ENS domain with invalid unicode characters

see Bee docs - Upload and download

see Bee API reference - GET /chunks

Parameters

Name	Type	Description
reference	ReferenceOrEns	Bee chunk reference in hex string (either 64 or 128 chars long) or ENS domain.
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<Data>

Defined in

bee-js/src/bee.ts:254

---

downloadData

▸ downloadData(reference, options?): Promise<Data>

Download data as a byte array

throws TypeError if some of the input parameters is not expected type

throws BeeArgumentError if there is passed ENS domain with invalid unicode characters

see Bee docs - Upload and download

see Bee API reference - GET /bytes

Parameters

Name	Type	Description
reference	ReferenceOrEns	Bee data reference in hex string (either 64 or 128 chars long) or ENS domain.
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<Data>

Defined in

bee-js/src/bee.ts:186

---

downloadFile

▸ downloadFile(reference, path?, options?): Promise<FileData<Data>>

Download single file.

throws TypeError if some of the input parameters is not expected type

throws BeeArgumentError if there is passed ENS domain with invalid unicode characters

see Data

see Bee docs - Upload and download

see Bee API reference - GET /bzz

Parameters

Name	Type	Default value	Description
reference	ReferenceCidOrEns	undefined	Bee file reference in hex string (either 64 or 128 chars long), ENS domain or Swarm CID.
path	string	''	If reference points to manifest, then this parameter defines path to the file
options?	RequestOptions	undefined	Options that affects the request behavior

Returns

Promise<FileData<Data>>

Defined in

bee-js/src/bee.ts:328

---

downloadReadableData

▸ downloadReadableData(reference, options?): Promise<ReadableStream<Uint8Array>>

Download data as a Readable stream

throws TypeError if some of the input parameters is not expected type

throws BeeArgumentError if there is passed ENS domain with invalid unicode characters

see Bee docs - Upload and download

see Bee API reference - GET /bytes

Parameters

Name	Type	Description
reference	ReferenceOrEns	Bee data reference in hex string (either 64 or 128 chars long) or ENS domain.
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<ReadableStream<Uint8Array>>

Defined in

bee-js/src/bee.ts:203

---

downloadReadableFile

▸ downloadReadableFile(reference, path?, options?): Promise<FileData<ReadableStream<Uint8Array>>>

Download single file as a readable stream

throws TypeError if some of the input parameters is not expected type

throws BeeArgumentError if there is passed ENS domain with invalid unicode characters

see Bee docs - Upload and download

see Bee API reference - GET /bzz

Parameters

Name	Type	Default value	Description
reference	ReferenceCidOrEns	undefined	Bee file reference in hex string (either 64 or 128 chars long), ENS domain or Swarm CID.
path	string	''	If reference points to manifest / collections, then this parameter defines path to the file
options?	RequestOptions	undefined	Options that affects the request behavior

Returns

Promise<FileData<ReadableStream<Uint8Array>>>

Defined in

bee-js/src/bee.ts:351

---

getAllPins

▸ getAllPins(options?): Promise<Reference[]>

Get list of all locally pinned references

Warning! Not allowed when node is in Gateway mode!

see Bee docs - Pinning

Parameters

Name	Type	Description
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<Reference[]>

Defined in

bee-js/src/bee.ts:601

---

getAllTags

▸ getAllTags(options?): Promise<Tag[]>

Fetches all tags.

The listing is limited by options.limit. So you have to iterate using options.offset to get all tags.

Warning! Not allowed when node is in Gateway mode!

throws TypeError if limit or offset are not numbers or undefined

throws BeeArgumentError if limit or offset have invalid options

see Bee docs - Syncing / Tags

see Bee API reference - GET /tags

Parameters

Name	Type	Description
options?	AllTagsOptions	Options that affects the request behavior

Returns

Promise<Tag[]>

Defined in

bee-js/src/bee.ts:482

---

getJsonFeed

▸ getJsonFeed<T>(topic, options?): Promise<T>

High-level function that allows you to easily get data from feed. Returned data are parsed using JSON.parse().

This method also supports specification of signer object passed to constructor. The order of evaluation is:

• options.address
• options.signer
• this.signer

At least one of these has to be specified!

see Bee docs - Feeds

Type parameters

Name	Type
T	extends AnyJson

Parameters

Name	Type	Description
topic	string	Human readable string, that is internally hashed so there are no constrains there.
options?	JsonFeedOptions

Returns

Promise<T>

Defined in

bee-js/src/bee.ts:1017

---

getPin

▸ getPin(reference, options?): Promise<Pin>

Get pinning status of chunk with given reference

Warning! Not allowed when node is in Gateway mode!

throws TypeError if some of the input parameters is not expected type

throws BeeArgumentError if there is passed ENS domain with invalid unicode characters

see Bee docs - Pinning

Parameters

Name	Type	Description
reference	string | Reference	Bee data reference in hex string (either 64 or 128 chars long) or ENS domain.
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<Pin>

Defined in

bee-js/src/bee.ts:619

---

isConnected

▸ isConnected(options?): Promise<boolean>

Ping the Bee node to see if there is a live Bee node on the given URL.

Parameters

Name	Type	Description
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<boolean>

true if successful, false on error

Defined in

bee-js/src/bee.ts:1113

---

isFeedRetrievable

▸ isFeedRetrievable(type, owner, topic, index?, options?): Promise<boolean>

Functions that validates if feed is retrievable in the network.

If no index is passed then it check for "latest" update, which is a weaker guarantee as nobody can be really sure what is the "latest" update.

If index is passed then it validates all previous sequence index chunks if they are available as they are required to correctly resolve the feed upto the given index update.

Parameters

Name	Type
type	"sequence" | "epoch"
owner	string | Uint8Array | EthAddress
topic	string | Uint8Array | Topic
index?	Index
options?	RequestOptions

Returns

Promise<boolean>

Defined in

bee-js/src/bee.ts:676

---

isReferenceRetrievable

▸ isReferenceRetrievable(reference, options?): Promise<boolean>

Checks if content specified by reference is retrievable from the network.

throws TypeError if some of the input parameters is not expected type

throws BeeArgumentError if there is passed ENS domain with invalid unicode characters

see Bee API reference - GET /stewardship

Parameters

Name	Type	Description
reference	ReferenceOrEns	Bee data reference to be checked in hex string (either 64 or 128 chars long) or ENS domain.
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<boolean>

Defined in

bee-js/src/bee.ts:654

---

makeFeedReader

▸ makeFeedReader(type, topic, owner, options?): FeedReader

Make a new feed reader for downloading feed updates.

see Bee docs - Feeds

Parameters

Name	Type	Description
type	"sequence" | "epoch"	The type of the feed, can be 'epoch' or 'sequence'
topic	string | Uint8Array | Topic	Topic in hex or bytes
owner	string | Uint8Array | EthAddress	Owner's ethereum address in hex or bytes
options?	RequestOptions	Options that affects the request behavior

Returns

FeedReader

Defined in

bee-js/src/bee.ts:924

---

makeFeedTopic

▸ makeFeedTopic(topic): Topic

Make a new feed topic from a string

Because the topic has to be 32 bytes long this function hashes the input string to create a topic string of arbitrary length.

Parameters

Name	Type	Description
topic	string	The input string

Returns

Topic

Defined in

bee-js/src/bee.ts:1056

---

makeFeedWriter

▸ makeFeedWriter(type, topic, signer?, options?): FeedWriter

Make a new feed writer for updating feeds

see Bee docs - Feeds

Parameters

Name	Type	Description
type	"sequence" | "epoch"	The type of the feed, can be 'epoch' or 'sequence'
topic	string | Uint8Array | Topic	Topic in hex or bytes
signer?	string | Uint8Array | Signer	The signer's private key or a Signer instance that can sign data
options?	RequestOptions	Options that affects the request behavior

Returns

FeedWriter

Defined in

bee-js/src/bee.ts:949

---

makeSOCReader

▸ makeSOCReader(ownerAddress, options?): SOCReader

Returns an object for reading single owner chunks

see Bee docs - Chunk Types

Parameters

Name	Type	Description
ownerAddress	string | Uint8Array | EthAddress	The ethereum address of the owner
options?	RequestOptions	Options that affects the request behavior

Returns

SOCReader

Defined in

bee-js/src/bee.ts:1067

---

makeSOCWriter

▸ makeSOCWriter(signer?, options?): SOCWriter

Returns an object for reading and writing single owner chunks

see Bee docs - Chunk Types

Parameters

Name	Type	Description
signer?	string | Uint8Array | Signer	The signer's private key or a Signer instance that can sign data
options?	RequestOptions	Options that affects the request behavior

Returns

SOCWriter

Defined in

bee-js/src/bee.ts:1084

---

pin

▸ pin(reference, options?): Promise<void>

Pin local data with given reference

Warning! Not allowed when node is in Gateway mode!

throws TypeError if reference is in not correct format

see Bee docs - Pinning

Parameters

Name	Type	Description
reference	string | Reference	Data reference
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<void>

Defined in

bee-js/src/bee.ts:568

---

pssReceive

▸ pssReceive(topic, timeoutMsec?): Promise<Data>

Receive message with Postal Service for Swarm

Because sending a PSS message is slow and CPU intensive, it is not supposed to be used for general messaging but most likely for setting up an encrypted communication channel by sending an one-off message.

This is a helper function to wait for exactly one message to arrive and then cancel the subscription. Additionally a timeout can be provided for the message to arrive or else an error will be thrown.

Warning! Not allowed when node is in Gateway mode!

Warning! If connected Bee node is a light node, then he will never receive any message! This is because light nodes does not fully participate in the data exchange in Swarm network and hence the message won't arrive to them.

see Bee docs - PSS

see Bee API reference - GET /pss

Parameters

Name	Type	Default value	Description
topic	string	undefined	Topic name
timeoutMsec	number	0	Timeout in milliseconds

Returns

Promise<Data>

Message in byte array

Defined in

bee-js/src/bee.ts:847

---

pssSend

▸ pssSend(postageBatchId, topic, target, data, recipient?, options?): Promise<void>

Send data to recipient or target with Postal Service for Swarm.

Because sending a PSS message is slow and CPU intensive, it is not supposed to be used for general messaging but most likely for setting up an encrypted communication channel by sending an one-off message.

Warning! Not allowed when node is in Gateway mode!

Warning! If the recipient Bee node is a light node, then he will never receive the message! This is because light nodes does not fully participate in the data exchange in Swarm network and hence the message won't arrive to them.

throws TypeError if data, batchId, target or recipient are in invalid format

see Bee docs - PSS

see Bee API reference - POST /pss

Parameters

Name	Type	Description
postageBatchId	string | BatchId	Postage BatchId that will be assigned to sent message
topic	string	Topic name
target	AddressPrefix	Target message address prefix. Has a limit on length. Recommend to use Utils.Pss.makeMaxTarget() to get the most specific target that Bee node will accept.
data	string | Uint8Array	Message to be sent
recipient?	string | PublicKey	Recipient public key
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<void>

Defined in

bee-js/src/bee.ts:734

---

pssSubscribe

▸ pssSubscribe(topic, handler): PssSubscription

Subscribe to messages for given topic with Postal Service for Swarm

Warning! Not allowed when node is in Gateway mode!

Warning! If connected Bee node is a light node, then he will never receive any message! This is because light nodes does not fully participate in the data exchange in Swarm network and hence the message won't arrive to them.

see Bee docs - PSS

see Bee API reference - GET /pss

Parameters

Name	Type	Description
topic	string	Topic name
handler	PssMessageHandler	Message handler interface

Returns

PssSubscription

Subscription to a given topic

Defined in

bee-js/src/bee.ts:776

---

retrieveTag

▸ retrieveTag(tagUid, options?): Promise<Tag>

Retrieve tag information from Bee node

Warning! Not allowed when node is in Gateway mode!

throws TypeError if tagUid is in not correct format

see Bee docs - Syncing / Tags

see Bee API reference - GET /tags/{uid}

Parameters

Name	Type	Description
tagUid	number | Tag	UID or tag object to be retrieved
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<Tag>

Defined in

bee-js/src/bee.ts:502

---

reuploadPinnedData

▸ reuploadPinnedData(reference, options?): Promise<void>

Instructs the Bee node to reupload a locally pinned data into the network.

throws BeeArgumentError if the reference is not locally pinned

throws TypeError if some of the input parameters is not expected type

throws BeeArgumentError if there is passed ENS domain with invalid unicode characters

see Bee API reference - PUT /stewardship

Parameters

Name	Type	Description
reference	ReferenceOrEns	Bee data reference to be re-uploaded in hex string (either 64 or 128 chars long) or ENS domain.
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<void>

Defined in

bee-js/src/bee.ts:637

---

setJsonFeed

▸ setJsonFeed<T>(postageBatchId, topic, data, options?): Promise<Reference>

High-level function that allows you to easily set JSON data to feed. JSON-like data types are supported.

The default Signer of Bee instance is used if options.signer is not specified. If none of those two is set error is thrown.

throws BeeError if options.signer is not specified nor the default Signer on Bee's instance is specified.

see Bee docs - Feeds

Type parameters

Name	Type
T	extends AnyJson

Parameters

Name	Type	Description
postageBatchId	string | BatchId	Postage BatchId to be used to upload the data with
topic	string	Human readable string, that is internally hashed so there are no constrains there.
data	T	JSON compatible data
options?	JsonFeedOptions

Returns

Promise<Reference>

Defined in

bee-js/src/bee.ts:982

---

unpin

▸ unpin(reference, options?): Promise<void>

Unpin local data with given reference

Warning! Not allowed when node is in Gateway mode!

throws TypeError if reference is in not correct format

see Bee docs - Pinning

Parameters

Name	Type	Description
reference	string | Reference	Data reference
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<void>

Defined in

bee-js/src/bee.ts:586

---

updateTag

▸ updateTag(tagUid, reference, options?): Promise<void>

Update tag's total chunks count.

This is important if you are uploading individual chunks with a tag. Then upon finishing the final root chunk, you can use this method to update the total chunks count for the tag.

Warning! Not allowed when node is in Gateway mode!

throws TypeError if tagUid is in not correct format

throws BeeResponse error if something went wrong on the Bee node side while deleting the tag.

see Bee docs - Syncing / Tags

see Bee API reference - PATCH /tags/{uid}

Parameters

Name	Type	Description
tagUid	number | Tag	UID or tag object to be retrieved
reference	string | Reference	The root reference that contains all the chunks to be counted
options?	RequestOptions	Options that affects the request behavior

Returns

Promise<void>

Defined in

bee-js/src/bee.ts:548

---

uploadChunk

▸ uploadChunk(postageBatchId, data, options?): Promise<Reference>

Upload chunk to a Bee node

see Bee docs - Upload and download

see Bee API reference - POST /chunks

Parameters

Name	Type	Description
postageBatchId	string | BatchId	Postage BatchId to be used to upload the chunk with
data	Uint8Array	Raw chunk to be uploaded
options?	UploadOptions	Additional options like tag, encryption, pinning, content-type and request options

Returns

Promise<Reference>

reference is a content hash of the data

Defined in

bee-js/src/bee.ts:224

---

uploadCollection

▸ uploadCollection(postageBatchId, collection, options?): Promise<UploadResultWithCid>

Upload Collection that you can assembly yourself.

The returned UploadResult.tag might be undefined if called in CORS-enabled environment. This will be fixed upon next Bee release. https://github.com/ethersphere/bee-js/issues/406

Parameters

Name	Type	Description
postageBatchId	string | BatchId
collection	Collection<Uint8Array | Readable>
options?	CollectionUploadOptions	Collections and request options

Returns

Promise<UploadResultWithCid>

Defined in

bee-js/src/bee.ts:405

---

uploadData

▸ uploadData(postageBatchId, data, options?): Promise<UploadResult>

Upload data to a Bee node

see Bee docs - Upload and download

see Bee API reference - POST /bytes

Parameters

Name	Type	Description
postageBatchId	string | BatchId	Postage BatchId to be used to upload the data with
data	string | Uint8Array	Data to be uploaded
options?	UploadOptions	Additional options like tag, encryption, pinning, content-type and request options

Returns

Promise<UploadResult>

reference is a content hash of the data

Defined in

bee-js/src/bee.ts:163

---

uploadFile

▸ uploadFile(postageBatchId, data, name?, options?): Promise<UploadResultWithCid>

Upload single file to a Bee node.

To make sure that you won't loose critical data it is highly recommended to also locally pin the data with options.pin = true

see Bee docs - Keep your data alive / Postage stamps

see Bee docs - Upload and download

see Bee API reference - POST /bzz

Parameters

Name	Type	Description
postageBatchId	string | BatchId	Postage BatchId to be used to upload the data with
data	string | File | Uint8Array | Readable	Data or file to be uploaded
name?	string	Optional name of the uploaded file
options?	FileUploadOptions	Additional options like tag, encryption, pinning, content-type and request options

Returns

Promise<UploadResultWithCid>

reference is a content hash of the file

Defined in

bee-js/src/bee.ts:277

---

uploadFiles

▸ uploadFiles(postageBatchId, fileList, options?): Promise<UploadResultWithCid>

Upload collection of files to a Bee node

Uses the FileList API from the browser.

The returned UploadResult.tag might be undefined if called in CORS-enabled environment. This will be fixed upon next Bee release. https://github.com/ethersphere/bee-js/issues/406

see Bee docs - Keep your data alive / Postage stamps

see Bee docs - Upload directory

see Bee API reference - POST /bzz

Parameters

Name	Type	Description
postageBatchId	string | BatchId	Postage BatchId to be used to upload the data with
fileList	FileList | File[]	list of files to be uploaded
options?	CollectionUploadOptions	Additional options like tag, encryption, pinning and request options

Returns

Promise<UploadResultWithCid>

Defined in

bee-js/src/bee.ts:378

---

uploadFilesFromDirectory

▸ uploadFilesFromDirectory(postageBatchId, dir, options?): Promise<UploadResultWithCid>

Upload collection of files.

Available only in Node.js as it uses the fs module.

The returned UploadResult.tag might be undefined if called in CORS-enabled environment. This will be fixed upon next Bee release. https://github.com/ethersphere/bee-js/issues/406

see Bee docs - Keep your data alive / Postage stamps

see Bee docs - Upload directory

see Bee API reference - POST /bzz

Parameters

Name	Type	Description
postageBatchId	string | BatchId	Postage BatchId to be used to upload the data with
dir	string	the path of the files to be uploaded
options?	CollectionUploadOptions	Additional options like tag, encryption, pinning and request options

Returns

Promise<UploadResultWithCid>

Defined in

bee-js/src/bee.ts:437