diff --git a/README.md b/README.md index b91e0fdf..935d3f2a 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ Check both out at the release you are documenting, then run: $ npm run generate-api ``` -This drives typedoc via `typedoc.config.mjs` and reshapes the output into the layout the site expects: it flattens the `Utils` namespace into `docs/api/namespaces/Utils`, turns the generated index into `Overview.md`, reduces references to TypeScript's own `lib.*.d.ts` to a machine-independent form, and links the `@ethersphere/core-sdk` re-exports against the core-sdk clone (`scripts/fix-core-sdk-links.mjs`, also runnable on its own as `npm run fix-api-links`). +This drives typedoc via `typedoc.config.mjs` and reshapes the output into the layout the site expects: it lifts the main entry point's pages out of the `bee-js/src` directory typedoc nests them in, flattens the `Utils` namespace into `docs/api/namespaces/Utils`, folds the namespace class pages into `docs/api/classes` alongside the rest, turns the generated index into `Overview.md`, reduces references to TypeScript's own `lib.*.d.ts` to a machine-independent form, and links the `@ethersphere/core-sdk` re-exports against the core-sdk clone (`scripts/fix-core-sdk-links.mjs`, also runnable on its own as `npm run fix-api-links`). Review the result as a diff against what is already committed. Anything unrelated to the bee-js release you are documenting means the toolchain moved, not the docs. @@ -63,7 +63,8 @@ Review the result as a diff against what is already committed. Anything unrelate - **`typedoc` and `typedoc-plugin-markdown` are pinned exactly.** A plugin upgrade rewrites unrelated pages and drowns the diff, so upgrade them deliberately, on their own. - **The `typescript` devDependency exists only for this step.** Nothing in this repository is TypeScript; typedoc compiles the bee-js sources with it, so it has to track what `sources/bee-js` requires or generation fails with type errors. - **`scripts/typedoc-frontmatter-titles.mjs` is not optional.** typedoc escapes markdown characters in page headings (`# Variable: NULL\_OWNER`), and Docusaurus takes the browser tab title, sidebar label, breadcrumbs and prev/next links from that raw heading without undoing the escapes. The plugin adds an unescaped frontmatter `title` instead. The escaping itself is not configurable upstream, and the heading has to stay escaped or MDX parses `\` as JSX. -- **The namespace classes are missing on purpose.** The classes behind `bee.data`, `bee.stamp` and the rest live in `src/modules/*.ts` and are not exported from bee-js's `src/index.ts`, so typedoc emits no pages for them. They cannot simply be added as entry points — their names collide with exported types (`Data`, `Tag`, `Pin`, `Collection`, `Cheque`, `Chunk`). They are documented by hand in `docs/documentation/overview.md`. +- **The namespace classes reach the reference through extra entry points.** The classes behind `bee.data`, `bee.stamp` and the rest live in `src/modules/*.ts` and are not exported from bee-js's `src/index.ts`, so typedoc would otherwise render them as the unlinkable type of a `Bee` property. `typedoc.config.mjs` adds `src/modules/*.ts` as entry points of their own to give them pages. Their names collide with exported types (`Data`, `Tag`, `Pin`, `Collection`, `Chunk`), which is harmless because each entry point is its own typedoc module — but it is also why nothing may fold those pages together with the exported types of the same name. +- **Multiple entry points are what puts every page under `bee-js/src`.** typedoc names a module directory after each entry point's path, so the whole reference arrives one subtree down. `generate-api.mjs` moves that subtree up as one piece, which is what keeps the relative links inside it correct without rewriting any of them. Should bee-js move `src/modules` or rename the entry file, that lift is the first thing to break. ## Maintainers diff --git a/TASK.md b/TASK.md new file mode 100644 index 00000000..4f7b1f7e --- /dev/null +++ b/TASK.md @@ -0,0 +1,10 @@ +# Current task + +There are several open issues with titles only. Maybe they are already fixed. Please assess them: + +- New functions: getWithdrawableStake, withdrawSurplusStake and migrateStake +- New functions: withdrawBZZToExternalWallet and withdrawDAIToExternalWallet +- Deprecation: withdrawTokens and depositTokens +- new Bytes is unnecessary, simply use toHex() on the returned classes + +Please note that the methods in these issues are from before the namespace restructuring, so you'll have to cross-check with the wandered method names. diff --git a/docs/api/Overview.md b/docs/api/Overview.md index ee5fd6c4..09486a13 100644 --- a/docs/api/Overview.md +++ b/docs/api/Overview.md @@ -5,10 +5,6 @@ slug: /api/ sidebar_position: 0 --- -:::info Namespace methods -This reference covers everything `@ethersphere/bee-js` exports. The classes behind `bee.data`, `bee.file`, `bee.stamp` and the other [namespaces](../documentation/overview.md#namespaces) are internal to the library and have no page of their own here. The [SDK Overview](../documentation/overview.md#bee-api) lists every namespaced method together with the Bee endpoint it calls. -::: - ## Namespaces - [Utils](./namespaces/Utils/approximateOverheadForRedundancyLevel.md) @@ -21,6 +17,7 @@ This reference covers everything `@ethersphere/bee-js` exports. The classes behi ## Classes +- [Balance](classes/Balance.md) - [BatchId](classes/BatchId.md) - [Bee](classes/Bee.md) - [BeeArgumentError](classes/BeeArgumentError.md) @@ -28,24 +25,44 @@ This reference covers everything `@ethersphere/bee-js` exports. The classes behi - [BeeResponseError](classes/BeeResponseError.md) - [Bytes](classes/Bytes.md) - [BZZ](classes/BZZ.md) +- [Cheque](classes/Cheque.md) +- [Chequebook](classes/Chequebook.md) +- [Chunk](classes/Chunk.md) - [ChunkBuilder](classes/ChunkBuilder.md) - [ChunkSplitter](classes/ChunkSplitter.md) +- [Collection](classes/Collection.md) +- [Connectivity](classes/Connectivity.md) - [DAI](classes/DAI.md) +- [Data](classes/Data.md) - [Duration](classes/Duration.md) - [EthAddress](classes/EthAddress.md) +- [Feed](classes/Feed.md) - [FeedIndex](classes/FeedIndex.md) +- [File](classes/File.md) +- [Grantee](classes/Grantee.md) - [Identifier](classes/Identifier.md) - [MantarayNode](classes/MantarayNode.md) +- [Messaging](classes/Messaging.md) - [PeerAddress](classes/PeerAddress.md) +- [Pin](classes/Pin.md) - [PrivateKey](classes/PrivateKey.md) - [PublicKey](classes/PublicKey.md) - [Reference](classes/Reference.md) +- [Settlement](classes/Settlement.md) - [Signature](classes/Signature.md) - [Size](classes/Size.md) +- [Soc](classes/Soc.md) - [Span](classes/Span.md) +- [Stake](classes/Stake.md) +- [Stamp](classes/Stamp.md) - [Stamper](classes/Stamper.md) +- [Status](classes/Status.md) +- [Storage](classes/Storage.md) +- [Tag](classes/Tag.md) - [Topic](classes/Topic.md) +- [Transaction](classes/Transaction.md) - [TransactionId](classes/TransactionId.md) +- [Wallet](classes/Wallet.md) ## Interfaces diff --git a/docs/api/classes/Balance.md b/docs/api/classes/Balance.md new file mode 100644 index 00000000..b89052b2 --- /dev/null +++ b/docs/api/classes/Balance.md @@ -0,0 +1,125 @@ +# Class: Balance + +Defined in: [bee-js/src/modules/balance.ts:12](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/balance.ts#L12) + +SWAP balance operations. Related to the bandwidth incentives and the chequebook. + +Accessed as `bee.balance`. + +## Constructors + +### Constructor + +> **new Balance**(`context`): `Balance` + +Defined in: [bee-js/src/modules/balance.ts:13](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/balance.ts#L13) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Balance` + +## Methods + +### getAll() + +> **getAll**(`requestOptions?`): `Promise`\<[`BalanceResponse`](../interfaces/BalanceResponse.md)\> + +Defined in: [bee-js/src/modules/balance.ts:20](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/balance.ts#L20) + +Gets the SWAP balances with all known peers including prepaid services. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BalanceResponse`](../interfaces/BalanceResponse.md)\> + +*** + +### getAllPastDueConsumption() + +> **getAllPastDueConsumption**(`requestOptions?`): `Promise`\<[`BalanceResponse`](../interfaces/BalanceResponse.md)\> + +Defined in: [bee-js/src/modules/balance.ts:41](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/balance.ts#L41) + +Gets the past due consumption balances for all known peers. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BalanceResponse`](../interfaces/BalanceResponse.md)\> + +*** + +### getAllPastDueConsumptionForPeer() + +> **getAllPastDueConsumptionForPeer**(`address`, `requestOptions?`): `Promise`\<[`PeerBalance`](../interfaces/PeerBalance.md)\> + +Defined in: [bee-js/src/modules/balance.ts:51](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/balance.ts#L51) + +Gets the past due consumption balance for a specific peer. + +#### Parameters + +##### address + +Swarm address of peer + +`string` | [`PeerAddress`](../classes/PeerAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`PeerBalance`](../interfaces/PeerBalance.md)\> + +*** + +### getPeer() + +> **getPeer**(`address`, `requestOptions?`): `Promise`\<[`PeerBalance`](../interfaces/PeerBalance.md)\> + +Defined in: [bee-js/src/modules/balance.ts:30](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/balance.ts#L30) + +Gets the SWAP balances for a specific peer including prepaid services. + +#### Parameters + +##### address + +Swarm address of peer + +`string` | [`PeerAddress`](../classes/PeerAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`PeerBalance`](../interfaces/PeerBalance.md)\> diff --git a/docs/api/classes/Bee.md b/docs/api/classes/Bee.md index b7c3d65f..b12dd03f 100644 --- a/docs/api/classes/Bee.md +++ b/docs/api/classes/Bee.md @@ -46,7 +46,7 @@ const bee = new Bee('http://localhost:1633') ### balance -> `readonly` **balance**: `Balance` +> `readonly` **balance**: [`Balance`](Balance.md) Defined in: [bee-js/src/bee.ts:148](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L148) @@ -56,7 +56,7 @@ SWAP balance operations. Related to the bandwidth incentives and the chequebook. ### cheque -> `readonly` **cheque**: `Cheque` +> `readonly` **cheque**: [`Cheque`](Cheque.md) Defined in: [bee-js/src/bee.ts:198](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L198) @@ -66,7 +66,7 @@ Cheque operations (last cheques and cashouts). ### chequebook -> `readonly` **chequebook**: `Chequebook` +> `readonly` **chequebook**: [`Chequebook`](Chequebook.md) Defined in: [bee-js/src/bee.ts:193](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L193) @@ -76,7 +76,7 @@ Chequebook contract operations (address, balance, deposit, withdraw). ### chunk -> `readonly` **chunk**: `Chunk` +> `readonly` **chunk**: [`Chunk`](Chunk.md) Defined in: [bee-js/src/bee.ts:238](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L238) @@ -86,7 +86,7 @@ Chunk operations backed by the `/chunks` endpoint. ### collection -> `readonly` **collection**: `Collection` +> `readonly` **collection**: [`Collection`](Collection.md) Defined in: [bee-js/src/bee.ts:248](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L248) @@ -96,7 +96,7 @@ Collection (multi-file) operations backed by the `/bzz` endpoint. ### connectivity -> `readonly` **connectivity**: `Connectivity` +> `readonly` **connectivity**: [`Connectivity`](Connectivity.md) Defined in: [bee-js/src/bee.ts:168](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L168) @@ -106,7 +106,7 @@ Peer, topology and network connectivity operations. ### data -> `readonly` **data**: `Data` +> `readonly` **data**: [`Data`](Data.md) Defined in: [bee-js/src/bee.ts:233](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L233) @@ -116,7 +116,7 @@ Raw data operations backed by the `/bytes` endpoint. ### feed -> `readonly` **feed**: `Feed` +> `readonly` **feed**: [`Feed`](Feed.md) Defined in: [bee-js/src/bee.ts:223](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L223) @@ -126,7 +126,7 @@ Feed operations. ### file -> `readonly` **file**: `File` +> `readonly` **file**: [`File`](File.md) Defined in: [bee-js/src/bee.ts:243](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L243) @@ -136,7 +136,7 @@ Single-file operations backed by the `/bzz` endpoint. ### grantee -> `readonly` **grantee**: `Grantee` +> `readonly` **grantee**: [`Grantee`](Grantee.md) Defined in: [bee-js/src/bee.ts:213](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L213) @@ -146,7 +146,7 @@ Grantee (access control) operations. ### messaging -> `readonly` **messaging**: `Messaging` +> `readonly` **messaging**: [`Messaging`](Messaging.md) Defined in: [bee-js/src/bee.ts:218](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L218) @@ -175,7 +175,7 @@ The block time for `gnosis` is `5` seconds, and for `sepolia` it is `15` seconds ### pin -> `readonly` **pin**: `Pin` +> `readonly` **pin**: [`Pin`](Pin.md) Defined in: [bee-js/src/bee.ts:208](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L208) @@ -185,7 +185,7 @@ Local pinning operations. ### settlement -> `readonly` **settlement**: `Settlement` +> `readonly` **settlement**: [`Settlement`](Settlement.md) Defined in: [bee-js/src/bee.ts:153](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L153) @@ -210,7 +210,7 @@ must be provided with a private key in their respective function calls. ### soc -> `readonly` **soc**: `Soc` +> `readonly` **soc**: [`Soc`](Soc.md) Defined in: [bee-js/src/bee.ts:228](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L228) @@ -220,7 +220,7 @@ Single owner chunk (SOC) reader/writer operations. ### stake -> `readonly` **stake**: `Stake` +> `readonly` **stake**: [`Stake`](Stake.md) Defined in: [bee-js/src/bee.ts:163](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L163) @@ -230,7 +230,7 @@ Staking operations. ### stamp -> `readonly` **stamp**: `Stamp` +> `readonly` **stamp**: [`Stamp`](Stamp.md) Defined in: [bee-js/src/bee.ts:183](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L183) @@ -240,7 +240,7 @@ Low-level postage batch (stamp) operations. ### status -> `readonly` **status**: `Status` +> `readonly` **status**: [`Status`](Status.md) Defined in: [bee-js/src/bee.ts:173](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L173) @@ -250,7 +250,7 @@ Node status, health, version and chain/reserve state operations. ### storage -> `readonly` **storage**: `Storage` +> `readonly` **storage**: [`Storage`](Storage.md) Defined in: [bee-js/src/bee.ts:188](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L188) @@ -260,7 +260,7 @@ Ergonomic storage operations expressed in terms of size and duration. ### tag -> `readonly` **tag**: `Tag` +> `readonly` **tag**: [`Tag`](Tag.md) Defined in: [bee-js/src/bee.ts:203](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L203) @@ -270,7 +270,7 @@ Tag operations for tracking upload and synchronization progress. ### transaction -> `readonly` **transaction**: `Transaction` +> `readonly` **transaction**: [`Transaction`](Transaction.md) Defined in: [bee-js/src/bee.ts:158](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L158) @@ -296,7 +296,7 @@ Bee node API URL. ### wallet -> `readonly` **wallet**: `Wallet` +> `readonly` **wallet**: [`Wallet`](Wallet.md) Defined in: [bee-js/src/bee.ts:178](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/bee.ts#L178) diff --git a/docs/api/classes/Cheque.md b/docs/api/classes/Cheque.md new file mode 100644 index 00000000..fd39e219 --- /dev/null +++ b/docs/api/classes/Cheque.md @@ -0,0 +1,135 @@ +# Class: Cheque + +Defined in: [bee-js/src/modules/cheque.ts:18](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/cheque.ts#L18) + +Cheque operations (last cheques and cashouts). + +Accessed as `bee.cheque`. + +## Constructors + +### Constructor + +> **new Cheque**(`context`): `Cheque` + +Defined in: [bee-js/src/modules/cheque.ts:19](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/cheque.ts#L19) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Cheque` + +## Methods + +### cashoutLast() + +> **cashoutLast**(`address`, `options?`, `requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/cheque.ts:67](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/cheque.ts#L67) + +Cashes out the last cheque for a specific peer. + +#### Parameters + +##### address + +Swarm address of peer + +`string` | [`PeerAddress`](../classes/PeerAddress.md) + +##### options? + +[`TransactionOptions`](../interfaces/TransactionOptions.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +*** + +### getAllLatest() + +> **getAllLatest**(`requestOptions?`): `Promise`\<[`LastChequesResponse`](../interfaces/LastChequesResponse.md)\> + +Defined in: [bee-js/src/modules/cheque.ts:26](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/cheque.ts#L26) + +Gets the last cheques for all peers. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`LastChequesResponse`](../interfaces/LastChequesResponse.md)\> + +*** + +### getAllLatestForPeer() + +> **getAllLatestForPeer**(`address`, `requestOptions?`): `Promise`\<[`LastChequesForPeerResponse`](../interfaces/LastChequesForPeerResponse.md)\> + +Defined in: [bee-js/src/modules/cheque.ts:36](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/cheque.ts#L36) + +Gets the last cheques for a specific peer. + +#### Parameters + +##### address + +Overlay address of peer. + +`string` | [`PeerAddress`](../classes/PeerAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`LastChequesForPeerResponse`](../interfaces/LastChequesForPeerResponse.md)\> + +*** + +### getLastCashoutAction() + +> **getLastCashoutAction**(`address`, `requestOptions?`): `Promise`\<[`LastCashoutActionResponse`](../interfaces/LastCashoutActionResponse.md)\> + +Defined in: [bee-js/src/modules/cheque.ts:51](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/cheque.ts#L51) + +Gets the last cashout action for a specific peer. + +#### Parameters + +##### address + +Overlay address of peer. + +`string` | [`PeerAddress`](../classes/PeerAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`LastCashoutActionResponse`](../interfaces/LastCashoutActionResponse.md)\> diff --git a/docs/api/classes/Chequebook.md b/docs/api/classes/Chequebook.md new file mode 100644 index 00000000..f38264a0 --- /dev/null +++ b/docs/api/classes/Chequebook.md @@ -0,0 +1,137 @@ +# Class: Chequebook + +Defined in: [bee-js/src/modules/chequebook.ts:13](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chequebook.ts#L13) + +Chequebook contract operations (address, balance, deposit, withdraw). + +Accessed as `bee.chequebook`. + +## Constructors + +### Constructor + +> **new Chequebook**(`context`): `Chequebook` + +Defined in: [bee-js/src/modules/chequebook.ts:14](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chequebook.ts#L14) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Chequebook` + +## Methods + +### deposit() + +> **deposit**(`amount`, `gasPrice?`, `requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/chequebook.ts:41](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chequebook.ts#L41) + +Deposits tokens from the node wallet into the chequebook. + +#### Parameters + +##### amount + +Amount of BZZ tokens to deposit. If not providing a `BZZ` instance, the amount is denoted in PLUR. + +`string` | `bigint` | [`BZZ`](../classes/BZZ.md) | [`NumberString`](../type-aliases/NumberString.md) + +##### gasPrice? + +Gas Price in WEI for the transaction call + +`string` | `bigint` | [`NumberString`](../type-aliases/NumberString.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +*** + +### getAddress() + +> **getAddress**(`requestOptions?`): `Promise`\<[`ChequebookAddressResponse`](../interfaces/ChequebookAddressResponse.md)\> + +Defined in: [bee-js/src/modules/chequebook.ts:21](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chequebook.ts#L21) + +Gets the address of the deployed chequebook. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`ChequebookAddressResponse`](../interfaces/ChequebookAddressResponse.md)\> + +*** + +### getBalance() + +> **getBalance**(`requestOptions?`): `Promise`\<[`ChequebookBalanceResponse`](../interfaces/ChequebookBalanceResponse.md)\> + +Defined in: [bee-js/src/modules/chequebook.ts:30](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chequebook.ts#L30) + +Gets the balance of the chequebook. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`ChequebookBalanceResponse`](../interfaces/ChequebookBalanceResponse.md)\> + +*** + +### withdraw() + +> **withdraw**(`amount`, `gasPrice?`, `requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/chequebook.ts:61](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chequebook.ts#L61) + +Withdraws tokens from the chequebook to the node wallet. + +#### Parameters + +##### amount + +Amount of BZZ tokens to withdraw. If not providing a `BZZ` instance, the amount is denoted in PLUR. + +`string` | `bigint` | [`BZZ`](../classes/BZZ.md) | [`NumberString`](../type-aliases/NumberString.md) + +##### gasPrice? + +Gas Price in WEI for the transaction call. + +`string` | `bigint` | [`NumberString`](../type-aliases/NumberString.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> diff --git a/docs/api/classes/Chunk.md b/docs/api/classes/Chunk.md new file mode 100644 index 00000000..862be0b9 --- /dev/null +++ b/docs/api/classes/Chunk.md @@ -0,0 +1,101 @@ +# Class: Chunk + +Defined in: [bee-js/src/modules/chunk.ts:15](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chunk.ts#L15) + +Chunk operations backed by the `/chunks` endpoint. + +Accessed as `bee.chunk`. + +## Constructors + +### Constructor + +> **new Chunk**(`context`): `Chunk` + +Defined in: [bee-js/src/modules/chunk.ts:16](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chunk.ts#L16) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Chunk` + +## Methods + +### download() + +> **download**(`reference`, `options?`, `requestOptions?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\> + +Defined in: [bee-js/src/modules/chunk.ts:67](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chunk.ts#L67) + +Downloads a chunk as a `Uint8Array`. + +#### Parameters + +##### reference + +Bee chunk reference in hex string (either 64 or 128 chars long) or ENS domain. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### options? + +[`DownloadOptions`](../interfaces/DownloadOptions.md) + +Options that affects the request behavior + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\> + +*** + +### upload() + +> **upload**(`stamp`, `data`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/chunk.ts:28](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/chunk.ts#L28) + +Uploads a chunk to the network. + +Chunks uploaded with this method should be retrieved with [download](#download). + +#### Parameters + +##### stamp + +Postage Batch ID or an Envelope created with the `bee.createEnvelope` method. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) | [`EnvelopeWithBatchId`](../interfaces/EnvelopeWithBatchId.md) + +##### data + +Raw chunk to be uploaded (Content Addressed Chunk or Single Owner Chunk) + +`Uint8Array`\<`ArrayBufferLike`\> | [`Chunk`](../interfaces/Chunk.md) | [`SingleOwnerChunk`](../interfaces/SingleOwnerChunk.md) + +##### options? + +[`UploadOptions`](../interfaces/UploadOptions.md) + +Additional options like tag, encryption, pinning, content-type and request options + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> diff --git a/docs/api/classes/Collection.md b/docs/api/classes/Collection.md new file mode 100644 index 00000000..cdad3158 --- /dev/null +++ b/docs/api/classes/Collection.md @@ -0,0 +1,247 @@ +# Class: Collection + +Defined in: [bee-js/src/modules/collection.ts:21](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/collection.ts#L21) + +Collection (multi-file) operations backed by the `/bzz` endpoint. + +Accessed as `bee.collection`. + +## Constructors + +### Constructor + +> **new Collection**(`context`): `Collection` + +Defined in: [bee-js/src/modules/collection.ts:22](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/collection.ts#L22) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Collection` + +## Methods + +### hashDirectory() + +> **hashDirectory**(`dir`): `Promise`\<[`Reference`](../classes/Reference.md)\> + +Defined in: [bee-js/src/modules/collection.ts:169](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/collection.ts#L169) + +Hashes a directory locally and returns the root hash (Swarm reference). + +The actual Swarm reference may be different as there is no canonical hashing of directories. + +#### Parameters + +##### dir + +`string` + +#### Returns + +`Promise`\<[`Reference`](../classes/Reference.md)\> + +*** + +### stream() + +> **stream**(`postageBatchId`, `files`, `onUploadProgress?`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/collection.ts:112](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/collection.ts#L112) + +Uploads a collection of files by streaming them to the Bee node, which supports arbitrary +sizes, but may be slower due to uploading chunks one by one. + +Only intended for the browser environment. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### files + +`File`[] | `FileList` + +##### onUploadProgress? + +(`progress`) => `void` + +##### options? + +[`UploadOptions`](../interfaces/UploadOptions.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +*** + +### streamFromDirectory() + +> **streamFromDirectory**(`postageBatchId`, `dir`, `onUploadProgress?`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/collection.ts:143](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/collection.ts#L143) + +Uploads a directory by streaming its contents directly to the Bee node, which supports +arbitrary directory sizes, but may be slower due to uploading chunks one by one. + +Only intended for the Node.js environment. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### dir + +`string` + +##### onUploadProgress? + +(`progress`) => `void` + +##### options? + +[`CollectionUploadOptions`](../interfaces/CollectionUploadOptions.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +*** + +### upload() + +> **upload**(`postageBatchId`, `collection`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/collection.ts:32](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/collection.ts#L32) + +Uploads a collection that you assemble yourself. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### collection + +[`Collection`](../type-aliases/Collection.md) + +##### options? + +[`CollectionUploadOptions`](../interfaces/CollectionUploadOptions.md) + +Collection and request options + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +*** + +### uploadFromDirectory() + +> **uploadFromDirectory**(`postageBatchId`, `dir`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/collection.ts:83](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/collection.ts#L83) + +Uploads a collection of files from a directory on the filesystem. + +Available only in Node.js as it uses the `fs` module. + +#### Parameters + +##### postageBatchId + +Postage BatchId to be used to upload the data with + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### dir + +`string` + +the path of the files to be uploaded + +##### options? + +[`CollectionUploadOptions`](../interfaces/CollectionUploadOptions.md) + +Additional options like tag, encryption, pinning and request options + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +*** + +### uploadFromFileList() + +> **uploadFromFileList**(`postageBatchId`, `fileList`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/collection.ts:56](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/collection.ts#L56) + +Uploads a collection of files using the browser `FileList` API. + +#### Parameters + +##### postageBatchId + +Postage BatchId to be used to upload the data with + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### fileList + +list of files to be uploaded + +`File`[] | `FileList` + +##### options? + +[`CollectionUploadOptions`](../interfaces/CollectionUploadOptions.md) + +Additional options like tag, encryption, pinning and request options + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> diff --git a/docs/api/classes/Connectivity.md b/docs/api/classes/Connectivity.md new file mode 100644 index 00000000..373d2d6b --- /dev/null +++ b/docs/api/classes/Connectivity.md @@ -0,0 +1,244 @@ +# Class: Connectivity + +Defined in: [bee-js/src/modules/connectivity.ts:12](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L12) + +Peer, topology and network connectivity operations. + +Accessed as `bee.connectivity`. + +## Constructors + +### Constructor + +> **new Connectivity**(`context`): `Connectivity` + +Defined in: [bee-js/src/modules/connectivity.ts:13](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L13) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Connectivity` + +## Methods + +### checkConnection() + +> **checkConnection**(`requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/connectivity.ts:21](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L21) + +Pings the Bee node to see if there is a live Bee node on the given URL. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> + +#### Throws + +If connection was not successful throw error + +*** + +### getBlocklist() + +> **getBlocklist**(`requestOptions?`): `Promise`\<[`Peer`](../interfaces/Peer.md)[]\> + +Defined in: [bee-js/src/modules/connectivity.ts:71](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L71) + +Fetches the list of blocked peers for this node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Peer`](../interfaces/Peer.md)[]\> + +*** + +### getNodeAddresses() + +> **getNodeAddresses**(`requestOptions?`): `Promise`\<[`NodeAddresses`](../interfaces/NodeAddresses.md)\> + +Defined in: [bee-js/src/modules/connectivity.ts:62](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L62) + +Fetches the overlay, underlay, Ethereum, and other addresses of the Bee node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`NodeAddresses`](../interfaces/NodeAddresses.md)\> + +*** + +### getPeers() + +> **getPeers**(`requestOptions?`): `Promise`\<[`Peer`](../interfaces/Peer.md)[]\> + +Defined in: [bee-js/src/modules/connectivity.ts:80](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L80) + +Gets list of peers for this node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Peer`](../interfaces/Peer.md)[]\> + +*** + +### getTopology() + +> **getTopology**(`requestOptions?`): `Promise`\<[`Topology`](../interfaces/Topology.md)\> + +Defined in: [bee-js/src/modules/connectivity.ts:101](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L101) + +Fetches topology and connectivity information of the Bee node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Topology`](../interfaces/Topology.md)\> + +*** + +### isConnected() + +> **isConnected**(`requestOptions?`): `Promise`\<`boolean`\> + +Defined in: [bee-js/src/modules/connectivity.ts:31](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L31) + +Pings the Bee node to see if there is a live Bee node on the given URL. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`boolean`\> + +true if successful, false on error + +*** + +### isGateway() + +> **isGateway**(`requestOptions?`): `Promise`\<`boolean`\> + +Defined in: [bee-js/src/modules/connectivity.ts:49](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L49) + +Checks the `/gateway` endpoint to see if the remote API is a gateway. + +Do note that this is not a standard way to check for gateway nodes, +but some of the gateway tooling expose this endpoint. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`boolean`\> + +*** + +### ping() + +> **ping**(`peer`, `requestOptions?`): `Promise`\<[`PingResponse`](../interfaces/PingResponse.md)\> + +Defined in: [bee-js/src/modules/connectivity.ts:111](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L111) + +Pings a specific peer to check its availability. + +#### Parameters + +##### peer + +Overlay address of the peer to be pinged. + +`string` | [`PeerAddress`](../classes/PeerAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`PingResponse`](../interfaces/PingResponse.md)\> + +*** + +### removePeer() + +> **removePeer**(`peer`, `requestOptions?`): `Promise`\<[`RemovePeerResponse`](../interfaces/RemovePeerResponse.md)\> + +Defined in: [bee-js/src/modules/connectivity.ts:90](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/connectivity.ts#L90) + +Disconnects from a specific peer. + +#### Parameters + +##### peer + +Overlay address of the peer to be removed. + +`string` | [`PeerAddress`](../classes/PeerAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`RemovePeerResponse`](../interfaces/RemovePeerResponse.md)\> diff --git a/docs/api/classes/Data.md b/docs/api/classes/Data.md new file mode 100644 index 00000000..3567d8e5 --- /dev/null +++ b/docs/api/classes/Data.md @@ -0,0 +1,191 @@ +# Class: Data + +Defined in: [bee-js/src/modules/data.ts:22](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/data.ts#L22) + +Raw data operations backed by the `/bytes` endpoint. + +Accessed as `bee.data`. + +## Constructors + +### Constructor + +> **new Data**(`context`): `Data` + +Defined in: [bee-js/src/modules/data.ts:23](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/data.ts#L23) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Data` + +## Methods + +### download() + +> **download**(`resource`, `options?`, `requestOptions?`): `Promise`\<[`Bytes`](../classes/Bytes.md)\> + +Defined in: [bee-js/src/modules/data.ts:58](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/data.ts#L58) + +Downloads raw data through the `GET /bytes/{reference}` endpoint. + +#### Parameters + +##### resource + +Swarm reference, Swarm CID, or ENS domain. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### options? + +[`DownloadOptions`](../interfaces/DownloadOptions.md) + +Options that affects the request behavior + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Bytes`](../classes/Bytes.md)\> + +*** + +### downloadReadable() + +> **downloadReadable**(`resource`, `options?`, `requestOptions?`): `Promise`\<`ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\>\> + +Defined in: [bee-js/src/modules/data.ts:79](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/data.ts#L79) + +Downloads raw data through the `GET /bytes/{reference}` endpoint as a readable stream. + +Only tested in Node.js environment. + +#### Parameters + +##### resource + +Swarm reference, Swarm CID, or ENS domain. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### options? + +[`DownloadOptions`](../interfaces/DownloadOptions.md) + +Options that affects the request behavior. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\>\> + +*** + +### isRetrievable() + +> **isRetrievable**(`reference`, `requestOptions?`): `Promise`\<`boolean`\> + +Defined in: [bee-js/src/modules/data.ts:116](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/data.ts#L116) + +Checks if content specified by reference is retrievable from the network. + +#### Parameters + +##### reference + +Bee reference to be checked in hex string (either 64 or 128 chars long) or ENS domain. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`boolean`\> + +*** + +### probe() + +> **probe**(`reference`, `requestOptions?`): `Promise`\<[`ReferenceInformation`](../interfaces/ReferenceInformation.md)\> + +Defined in: [bee-js/src/modules/data.ts:101](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/data.ts#L101) + +Fetches content length for a `/bytes` reference through the `HEAD /bytes/{reference}` endpoint. + +#### Parameters + +##### reference + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`ReferenceInformation`](../interfaces/ReferenceInformation.md)\> + +*** + +### upload() + +> **upload**(`postageBatchId`, `data`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/data.ts:35](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/data.ts#L35) + +Uploads raw data through the `POST /bytes` endpoint. + +Data uploaded with this method should be retrieved with [download](#download). + +#### Parameters + +##### postageBatchId + +Usable Postage Batch ID with sufficient capacity to upload the data. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### data + +A `string` (text data) or `Uint8Array` (raw data) to be uploaded. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | `Blob` | `Readable` + +##### options? + +[`RedundantUploadOptions`](../interfaces/RedundantUploadOptions.md) + +Additional options like tag, encryption, pinning, content-type and request options. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> diff --git a/docs/api/classes/Feed.md b/docs/api/classes/Feed.md new file mode 100644 index 00000000..9544de0f --- /dev/null +++ b/docs/api/classes/Feed.md @@ -0,0 +1,219 @@ +# Class: Feed + +Defined in: [bee-js/src/modules/feed.ts:17](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/feed.ts#L17) + +Feed operations. + +Accessed as `bee.feed`. Delegates to the feed subsystem (`src/feed`). + +## Constructors + +### Constructor + +> **new Feed**(`context`): `Feed` + +Defined in: [bee-js/src/modules/feed.ts:18](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/feed.ts#L18) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Feed` + +## Methods + +### createManifest() + +> **createManifest**(`postageBatchId`, `topic`, `owner`, `options?`, `requestOptions?`): `Promise`\<[`Reference`](../classes/Reference.md)\> + +Defined in: [bee-js/src/modules/feed.ts:69](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/feed.ts#L69) + +Creates a feed manifest chunk and returns the reference to it. + +#### Parameters + +##### postageBatchId + +Postage BatchId to be used to create the Feed Manifest + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### topic + +Topic in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Topic`](../classes/Topic.md) + +##### owner + +Owner's ethereum address in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`EthAddress`](../classes/EthAddress.md) + +##### options? + +[`UploadOptions`](../interfaces/UploadOptions.md) + +Options that affect the request behavior + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Reference`](../classes/Reference.md)\> + +*** + +### fetchLatestUpdate() + +> **fetchLatestUpdate**(`topic`, `owner`, `requestOptions?`): `Promise`\<`FeedPayloadResult`\> + +Defined in: [bee-js/src/modules/feed.ts:100](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/feed.ts#L100) + +Fetches the latest feed update. + +#### Parameters + +##### topic + +Topic in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Topic`](../classes/Topic.md) + +##### owner + +Owner's ethereum address in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`EthAddress`](../classes/EthAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`FeedPayloadResult`\> + +*** + +### isRetrievable() + +> **isRetrievable**(`owner`, `topic`, `index?`, `options?`, `requestOptions?`): `Promise`\<`boolean`\> + +Defined in: [bee-js/src/modules/feed.ts:121](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/feed.ts#L121) + +Validates whether a feed is retrievable in the network. + +#### Parameters + +##### owner + +Owner's ethereum address in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`EthAddress`](../classes/EthAddress.md) + +##### topic + +Topic in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Topic`](../classes/Topic.md) + +##### index? + +[`FeedIndex`](../classes/FeedIndex.md) + +Optional feed index + +##### options? + +[`DownloadOptions`](../interfaces/DownloadOptions.md) + +Download options + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`boolean`\> + +*** + +### makeReader() + +> **makeReader**(`topic`, `owner`, `requestOptions?`): [`FeedReader`](../interfaces/FeedReader.md) + +Defined in: [bee-js/src/modules/feed.ts:27](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/feed.ts#L27) + +Makes a new feed reader for downloading feed updates. + +#### Parameters + +##### topic + +Topic in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Topic`](../classes/Topic.md) + +##### owner + +Owner's ethereum address in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`EthAddress`](../classes/EthAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +[`FeedReader`](../interfaces/FeedReader.md) + +*** + +### makeWriter() + +> **makeWriter**(`topic`, `signer?`, `requestOptions?`): [`FeedWriter`](../interfaces/FeedWriter.md) + +Defined in: [bee-js/src/modules/feed.ts:46](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/feed.ts#L46) + +Makes a new feed writer for updating feeds. + +#### Parameters + +##### topic + +Topic in hex or bytes + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Topic`](../classes/Topic.md) + +##### signer? + +The signer's private key. Falls back to the Bee instance signer. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`PrivateKey`](../classes/PrivateKey.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +[`FeedWriter`](../interfaces/FeedWriter.md) diff --git a/docs/api/classes/File.md b/docs/api/classes/File.md new file mode 100644 index 00000000..f243f26e --- /dev/null +++ b/docs/api/classes/File.md @@ -0,0 +1,153 @@ +# Class: File + +Defined in: [bee-js/src/modules/file.ts:16](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/file.ts#L16) + +Single-file operations backed by the `/bzz` endpoint. + +Accessed as `bee.file`. + +## Constructors + +### Constructor + +> **new File**(`context`): `File` + +Defined in: [bee-js/src/modules/file.ts:17](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/file.ts#L17) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`File` + +## Methods + +### download() + +> **download**(`resource`, `path`, `options?`, `requestOptions?`): `Promise`\<[`FileData`](../interfaces/FileData.md)\<[`Bytes`](../classes/Bytes.md)\>\> + +Defined in: [bee-js/src/modules/file.ts:74](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/file.ts#L74) + +Downloads a single file. + +#### Parameters + +##### resource + +Swarm reference, Swarm CID, or ENS domain. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### path + +`string` = `''` + +If reference points to manifest, then this parameter defines path to the file + +##### options? + +[`DownloadOptions`](../interfaces/DownloadOptions.md) + +Options that affects the request behavior + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`FileData`](../interfaces/FileData.md)\<[`Bytes`](../classes/Bytes.md)\>\> + +*** + +### downloadReadable() + +> **downloadReadable**(`reference`, `path`, `options?`, `requestOptions?`): `Promise`\<[`FileData`](../interfaces/FileData.md)\<`ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\>\>\> + +Defined in: [bee-js/src/modules/file.ts:100](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/file.ts#L100) + +Downloads a single file as a readable stream. + +#### Parameters + +##### reference + +Bee file reference in hex string (either 64 or 128 chars long), ENS domain or Swarm CID. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### path + +`string` = `''` + +If reference points to manifest / collections, then this parameter defines path to the file + +##### options? + +[`DownloadOptions`](../interfaces/DownloadOptions.md) + +Options that affects the request behavior + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`FileData`](../interfaces/FileData.md)\<`ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\>\>\> + +*** + +### upload() + +> **upload**(`postageBatchId`, `data`, `name?`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/file.ts:30](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/file.ts#L30) + +Uploads a single file to a Bee node. + +To download the file, use [download](#download). + +#### Parameters + +##### postageBatchId + +Postage BatchId to be used to upload the data with + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### data + +Data or file to be uploaded + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | `File` | `Readable` + +##### name? + +`string` + +Optional name of the uploaded file + +##### options? + +[`FileUploadOptions`](../interfaces/FileUploadOptions.md) + +Additional options like tag, encryption, pinning, content-type and request options + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> diff --git a/docs/api/classes/Grantee.md b/docs/api/classes/Grantee.md new file mode 100644 index 00000000..35bb3287 --- /dev/null +++ b/docs/api/classes/Grantee.md @@ -0,0 +1,137 @@ +# Class: Grantee + +Defined in: [bee-js/src/modules/grantee.ts:11](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/grantee.ts#L11) + +Grantee (access control) operations. + +Accessed as `bee.grantee`. + +## Constructors + +### Constructor + +> **new Grantee**(`context`): `Grantee` + +Defined in: [bee-js/src/modules/grantee.ts:12](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/grantee.ts#L12) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Grantee` + +## Methods + +### create() + +> **create**(`postageBatchId`, `grantees`, `requestOptions?`): `Promise`\<[`GranteesResult`](../interfaces/GranteesResult.md)\> + +Defined in: [bee-js/src/modules/grantee.ts:21](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/grantee.ts#L21) + +Creates grantees for a postage batch. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### grantees + +Public keys of the grantees. + +`string`[] | `Uint8Array`\<`ArrayBufferLike`\>[] | [`PublicKey`](../classes/PublicKey.md)[] + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`GranteesResult`](../interfaces/GranteesResult.md)\> + +*** + +### get() + +> **get**(`reference`, `requestOptions?`): `Promise`\<[`GetGranteesResult`](../interfaces/GetGranteesResult.md)\> + +Defined in: [bee-js/src/modules/grantee.ts:38](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/grantee.ts#L38) + +Retrieves the grantees for a given reference. + +#### Parameters + +##### reference + +The reference. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`GetGranteesResult`](../interfaces/GetGranteesResult.md)\> + +*** + +### patch() + +> **patch**(`postageBatchId`, `reference`, `history`, `grantees`, `requestOptions?`): `Promise`\<[`GranteesResult`](../interfaces/GranteesResult.md)\> + +Defined in: [bee-js/src/modules/grantee.ts:56](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/grantee.ts#L56) + +Updates the grantees of a specific reference and history. + +#### Parameters + +##### postageBatchId + +The ID of the postage batch. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### reference + +The reference. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### history + +The history. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### grantees + +The grantees to add and/or revoke. + +###### add? + +`string`[] \| `Uint8Array`\<`ArrayBufferLike`\>[] \| [`PublicKey`](../classes/PublicKey.md)[] + +###### revoke? + +`string`[] \| `Uint8Array`\<`ArrayBufferLike`\>[] \| [`PublicKey`](../classes/PublicKey.md)[] + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`GranteesResult`](../interfaces/GranteesResult.md)\> diff --git a/docs/api/classes/Messaging.md b/docs/api/classes/Messaging.md new file mode 100644 index 00000000..715b08b2 --- /dev/null +++ b/docs/api/classes/Messaging.md @@ -0,0 +1,242 @@ +# Class: Messaging + +Defined in: [bee-js/src/modules/messaging.ts:40](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/messaging.ts#L40) + +Messaging protocols — PSS (Postal Service for Swarm) and GSOC. Method names keep +their `pss`/`gsoc` prefixes to distinguish the two protocols within the namespace. + +Accessed as `bee.messaging`. + +## Constructors + +### Constructor + +> **new Messaging**(`context`): `Messaging` + +Defined in: [bee-js/src/modules/messaging.ts:41](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/messaging.ts#L41) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Messaging` + +## Methods + +### gsocMine() + +> **gsocMine**(`targetOverlay`, `identifier`, `proximity`): [`PrivateKey`](../classes/PrivateKey.md) + +Defined in: [bee-js/src/modules/messaging.ts:153](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/messaging.ts#L153) + +Mines the signer (a private key) to be used to send GSOC messages to the specific target overlay address. + +#### Parameters + +##### targetOverlay + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`PeerAddress`](../classes/PeerAddress.md) + +##### identifier + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Identifier`](../classes/Identifier.md) + +##### proximity + +`number` = `12` + +#### Returns + +[`PrivateKey`](../classes/PrivateKey.md) + +*** + +### gsocSend() + +> **gsocSend**(`postageBatchId`, `signer`, `identifier`, `data`, `options?`, `requestOptions?`): `Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +Defined in: [bee-js/src/modules/messaging.ts:188](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/messaging.ts#L188) + +Sends a GSOC message with the specified signer and identifier. + +**Warning! Only full nodes can accept GSOC messages.** + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### signer + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`PrivateKey`](../classes/PrivateKey.md) + +##### identifier + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Identifier`](../classes/Identifier.md) + +##### data + +`string` | `Uint8Array`\<`ArrayBufferLike`\> + +##### options? + +[`UploadOptions`](../interfaces/UploadOptions.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`UploadResult`](../interfaces/UploadResult.md)\> + +*** + +### gsocSubscribe() + +> **gsocSubscribe**(`address`, `identifier`, `handler`): [`GsocSubscription`](../interfaces/GsocSubscription.md) + +Defined in: [bee-js/src/modules/messaging.ts:215](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/messaging.ts#L215) + +Subscribes to GSOC messages for the specified owner (of the signer) and identifier. + +**Warning! Only full nodes can accept GSOC messages.** + +#### Parameters + +##### address + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`EthAddress`](../classes/EthAddress.md) + +##### identifier + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Identifier`](../classes/Identifier.md) + +##### handler + +[`GsocMessageHandler`](../interfaces/GsocMessageHandler.md) + +#### Returns + +[`GsocSubscription`](../interfaces/GsocSubscription.md) + +*** + +### pssReceive() + +> **pssReceive**(`topic`, `timeoutMsec`): `Promise`\<[`Bytes`](../classes/Bytes.md)\> + +Defined in: [bee-js/src/modules/messaging.ts:113](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/messaging.ts#L113) + +Receives a single message using the Postal Service for Swarm. + +**Warning! Only full nodes can accept PSS messages.** + +#### Parameters + +##### topic + +[`Topic`](../classes/Topic.md) + +Topic name + +##### timeoutMsec + +`number` = `0` + +Timeout in milliseconds + +#### Returns + +`Promise`\<[`Bytes`](../classes/Bytes.md)\> + +*** + +### pssSend() + +> **pssSend**(`postageBatchId`, `topic`, `target`, `data`, `recipient?`, `requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/messaging.ts:55](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/messaging.ts#L55) + +Sends data to a recipient or target with the Postal Service for Swarm. + +**Warning! Only full nodes can accept PSS messages.** + +#### Parameters + +##### postageBatchId + +Postage BatchId that will be assigned to the sent message. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### topic + +[`Topic`](../classes/Topic.md) + +Topic name + +##### target + +`string` + +Target message address prefix + +##### data + +Message to send + +`string` | `Uint8Array`\<`ArrayBufferLike`\> + +##### recipient? + +Optional recipient public key + +`string` | [`PublicKey`](../classes/PublicKey.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> + +*** + +### pssSubscribe() + +> **pssSubscribe**(`topic`, `handler`): [`PssSubscription`](../interfaces/PssSubscription.md) + +Defined in: [bee-js/src/modules/messaging.ts:79](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/messaging.ts#L79) + +Subscribes to messages for the given topic with the Postal Service for Swarm. + +**Warning! Only full nodes can accept PSS messages.** + +#### Parameters + +##### topic + +[`Topic`](../classes/Topic.md) + +Topic name + +##### handler + +[`PssMessageHandler`](../interfaces/PssMessageHandler.md) + +Message handler interface + +#### Returns + +[`PssSubscription`](../interfaces/PssSubscription.md) diff --git a/docs/api/classes/Pin.md b/docs/api/classes/Pin.md new file mode 100644 index 00000000..80f6a7c7 --- /dev/null +++ b/docs/api/classes/Pin.md @@ -0,0 +1,165 @@ +# Class: Pin + +Defined in: [bee-js/src/modules/pin.ts:12](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/pin.ts#L12) + +Local pinning operations. + +Accessed as `bee.pin`. + +## Constructors + +### Constructor + +> **new Pin**(`context`): `Pin` + +Defined in: [bee-js/src/modules/pin.ts:13](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/pin.ts#L13) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Pin` + +## Methods + +### add() + +> **add**(`reference`, `requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/pin.ts:21](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/pin.ts#L21) + +Pins local data with the given reference. + +#### Parameters + +##### reference + +Data reference + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> + +*** + +### get() + +> **get**(`reference`, `requestOptions?`): `Promise`\<[`Pin`](../interfaces/Pin.md)\> + +Defined in: [bee-js/src/modules/pin.ts:54](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/pin.ts#L54) + +Gets the pinning status of the chunk with the given reference. + +#### Parameters + +##### reference + +Data reference + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Pin`](../interfaces/Pin.md)\> + +*** + +### getAll() + +> **getAll**(`requestOptions?`): `Promise`\<[`Reference`](../classes/Reference.md)[]\> + +Defined in: [bee-js/src/modules/pin.ts:44](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/pin.ts#L44) + +Gets the list of all locally pinned references. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Reference`](../classes/Reference.md)[]\> + +*** + +### remove() + +> **remove**(`reference`, `requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/pin.ts:33](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/pin.ts#L33) + +Unpins local data with the given reference. + +#### Parameters + +##### reference + +Data reference + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> + +*** + +### reuploadData() + +> **reuploadData**(`postageBatchId`, `reference`, `requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/pin.ts:67](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/pin.ts#L67) + +Instructs the Bee node to reupload locally pinned data into the network. + +#### Parameters + +##### postageBatchId + +Postage Batch ID that will be used to re-upload the data. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### reference + +Data reference to be re-uploaded. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`Reference`](../classes/Reference.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> diff --git a/docs/api/classes/Settlement.md b/docs/api/classes/Settlement.md new file mode 100644 index 00000000..2a730009 --- /dev/null +++ b/docs/api/classes/Settlement.md @@ -0,0 +1,75 @@ +# Class: Settlement + +Defined in: [bee-js/src/modules/settlement.ts:11](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/settlement.ts#L11) + +Settlement operations. Related to the bandwidth incentives and the chequebook. + +Accessed as `bee.settlement`. + +## Constructors + +### Constructor + +> **new Settlement**(`context`): `Settlement` + +Defined in: [bee-js/src/modules/settlement.ts:12](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/settlement.ts#L12) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Settlement` + +## Methods + +### get() + +> **get**(`address`, `requestOptions?`): `Promise`\<[`Settlements`](../interfaces/Settlements.md)\> + +Defined in: [bee-js/src/modules/settlement.ts:20](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/settlement.ts#L20) + +Gets the amount of sent and received micropayments from settlements with a peer. + +#### Parameters + +##### address + +Swarm address of peer + +`string` | [`PeerAddress`](../classes/PeerAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Settlements`](../interfaces/Settlements.md)\> + +*** + +### getAll() + +> **getAll**(`requestOptions?`): `Promise`\<[`AllSettlements`](../interfaces/AllSettlements.md)\> + +Defined in: [bee-js/src/modules/settlement.ts:31](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/settlement.ts#L31) + +Gets settlements with all known peers and total amount sent or received. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`AllSettlements`](../interfaces/AllSettlements.md)\> diff --git a/docs/api/classes/Soc.md b/docs/api/classes/Soc.md new file mode 100644 index 00000000..fa725bef --- /dev/null +++ b/docs/api/classes/Soc.md @@ -0,0 +1,81 @@ +# Class: Soc + +Defined in: [bee-js/src/modules/soc.ts:11](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/soc.ts#L11) + +Single owner chunk (SOC) reader/writer operations. + +Accessed as `bee.soc`. + +## Constructors + +### Constructor + +> **new Soc**(`context`): `Soc` + +Defined in: [bee-js/src/modules/soc.ts:12](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/soc.ts#L12) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Soc` + +## Methods + +### makeReader() + +> **makeReader**(`ownerAddress`, `requestOptions?`): [`SOCReader`](../interfaces/SOCReader.md) + +Defined in: [bee-js/src/modules/soc.ts:20](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/soc.ts#L20) + +Returns an object for reading single owner chunks. + +#### Parameters + +##### ownerAddress + +The ethereum address of the owner + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`EthAddress`](../classes/EthAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +[`SOCReader`](../interfaces/SOCReader.md) + +*** + +### makeWriter() + +> **makeWriter**(`signer?`, `requestOptions?`): [`SOCWriter`](../interfaces/SOCWriter.md) + +Defined in: [bee-js/src/modules/soc.ts:35](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/soc.ts#L35) + +Returns an object for reading and writing single owner chunks. + +#### Parameters + +##### signer? + +The signer's private key. Falls back to the Bee instance signer. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`PrivateKey`](../classes/PrivateKey.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +[`SOCWriter`](../interfaces/SOCWriter.md) diff --git a/docs/api/classes/Stake.md b/docs/api/classes/Stake.md new file mode 100644 index 00000000..a24422b1 --- /dev/null +++ b/docs/api/classes/Stake.md @@ -0,0 +1,171 @@ +# Class: Stake + +Defined in: [bee-js/src/modules/stake.ts:15](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stake.ts#L15) + +Staking operations. + +Accessed as `bee.stake`. + +## Constructors + +### Constructor + +> **new Stake**(`context`): `Stake` + +Defined in: [bee-js/src/modules/stake.ts:16](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stake.ts#L16) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Stake` + +## Methods + +### deposit() + +> **deposit**(`amount`, `options?`, `requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/stake.ts:45](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stake.ts#L45) + +Stakes the given amount of BZZ. Initial deposit must be at least 10 BZZ. + +Be aware that staked BZZ tokens can **not** be withdrawn. + +#### Parameters + +##### amount + +Amount of BZZ tokens to be staked. If not providing a `BZZ` instance, the amount is denoted in PLUR. + +`string` | `bigint` | [`BZZ`](../classes/BZZ.md) | [`NumberString`](../type-aliases/NumberString.md) + +##### options? + +[`TransactionOptions`](../interfaces/TransactionOptions.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +*** + +### get() + +> **get**(`requestOptions?`): `Promise`\<[`BZZ`](../classes/BZZ.md)\> + +Defined in: [bee-js/src/modules/stake.ts:23](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stake.ts#L23) + +Gets the amount of staked BZZ. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BZZ`](../classes/BZZ.md)\> + +*** + +### getRedistributionState() + +> **getRedistributionState**(`requestOptions?`): `Promise`\<[`RedistributionState`](../interfaces/RedistributionState.md)\> + +Defined in: [bee-js/src/modules/stake.ts:85](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stake.ts#L85) + +Gets current status of node in redistribution game. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`RedistributionState`](../interfaces/RedistributionState.md)\> + +*** + +### getWithdrawable() + +> **getWithdrawable**(`requestOptions?`): `Promise`\<[`BZZ`](../classes/BZZ.md)\> + +Defined in: [bee-js/src/modules/stake.ts:32](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stake.ts#L32) + +Gets the amount of withdrawable staked BZZ. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BZZ`](../classes/BZZ.md)\> + +*** + +### migrate() + +> **migrate**(`requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/stake.ts:76](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stake.ts#L76) + +Withdraws all staked BZZ to the node wallet. + +**Only available when the staking contract is paused and is in the process of being migrated to a new contract!** + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +*** + +### withdrawSurplus() + +> **withdrawSurplus**(`requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/stake.ts:65](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stake.ts#L65) + +Withdraws all surplus staked BZZ to the node wallet. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> diff --git a/docs/api/classes/Stamp.md b/docs/api/classes/Stamp.md new file mode 100644 index 00000000..0850f53d --- /dev/null +++ b/docs/api/classes/Stamp.md @@ -0,0 +1,343 @@ +# Class: Stamp + +Defined in: [bee-js/src/modules/stamp.ts:29](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L29) + +Low-level postage batch (stamp) operations. + +Accessed as `bee.stamp`. For the ergonomic wrapper see `bee.storage`. + +## Constructors + +### Constructor + +> **new Stamp**(`context`): `Stamp` + +Defined in: [bee-js/src/modules/stamp.ts:30](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L30) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Stamp` + +## Methods + +### calculateTopUpForBZZ() + +> **calculateTopUpForBZZ**(`depth`, `bzz`, `requestOptions?`): `Promise`\<\{ `amount`: `bigint`; `duration`: [`Duration`](../classes/Duration.md); \}\> + +Defined in: [bee-js/src/modules/stamp.ts:108](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L108) + +Calculates the `amount` and expected duration extension for topping up a postage batch with a given BZZ value. + +#### Parameters + +##### depth + +`number` + +Depth of the postage batch to top up. + +##### bzz + +[`BZZ`](../classes/BZZ.md) + +The amount of BZZ to spend on the top-up. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<\{ `amount`: `bigint`; `duration`: [`Duration`](../classes/Duration.md); \}\> + +*** + +### create() + +> **create**(`amount`, `depth`, `options?`, `requestOptions?`): `Promise`\<[`BatchId`](../classes/BatchId.md)\> + +Defined in: [bee-js/src/modules/stamp.ts:42](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L42) + +Creates a new postage batch, spending BZZ tokens from the node wallet. + +Use `bee.storage.buy` for a more convenient way to create a postage batch. + +#### Parameters + +##### amount + +TTL parameter - 1 day at the minimum of 24,000 storage price requires an amount of 414,720,000. + +`string` | `bigint` | [`NumberString`](../type-aliases/NumberString.md) + +##### depth + +`number` + +Capacity parameter - 17..255. + +##### options? + +[`PostageBatchOptions`](../interfaces/PostageBatchOptions.md) + +Options for creation of postage batch + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BatchId`](../classes/BatchId.md)\> + +*** + +### dilute() + +> **dilute**(`postageBatchId`, `depth`, `requestOptions?`): `Promise`\<[`BatchId`](../classes/BatchId.md)\> + +Defined in: [bee-js/src/modules/stamp.ts:146](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L146) + +Dilutes a postage batch to extend its capacity by increasing its depth. + +#### Parameters + +##### postageBatchId + +Batch ID + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### depth + +`number` + +New depth for the batch + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BatchId`](../classes/BatchId.md)\> + +*** + +### get() + +> **get**(`postageBatchId`, `requestOptions?`, `encryption?`, `erasureCodeLevel?`): `Promise`\<[`PostageBatch`](../interfaces/PostageBatch.md)\> + +Defined in: [bee-js/src/modules/stamp.ts:165](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L165) + +Returns details for a specific postage batch. + +#### Parameters + +##### postageBatchId + +Batch ID + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +##### encryption? + +`boolean` + +Assume that uploads with this postage batch are encrypted, which skews the capacity. + +##### erasureCodeLevel? + +[`RedundancyLevel`](../enumerations/RedundancyLevel.md) + +Assume that uploads with this postage batch are erasure coded, which skews the capacity. + +#### Returns + +`Promise`\<[`PostageBatch`](../interfaces/PostageBatch.md)\> + +*** + +### getAll() + +> **getAll**(`requestOptions?`): `Promise`\<[`PostageBatch`](../interfaces/PostageBatch.md)[]\> + +Defined in: [bee-js/src/modules/stamp.ts:216](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L216) + +Returns all postage batches that belong to the node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`PostageBatch`](../interfaces/PostageBatch.md)[]\> + +*** + +### getAllGlobal() + +> **getAllGlobal**(`requestOptions?`): `Promise`\<[`GlobalPostageBatch`](../interfaces/GlobalPostageBatch.md)[]\> + +Defined in: [bee-js/src/modules/stamp.ts:225](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L225) + +Returns all globally available postage batches. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`GlobalPostageBatch`](../interfaces/GlobalPostageBatch.md)[]\> + +*** + +### getBuckets() + +> **getBuckets**(`postageBatchId`, `requestOptions?`): `Promise`\<[`PostageBatchBuckets`](../interfaces/PostageBatchBuckets.md)\> + +Defined in: [bee-js/src/modules/stamp.ts:202](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L202) + +Returns detailed information related to buckets for a specific postage batch. + +#### Parameters + +##### postageBatchId + +Batch ID + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`PostageBatchBuckets`](../interfaces/PostageBatchBuckets.md)\> + +*** + +### getGlobal() + +> **getGlobal**(`postageBatchId`, `requestOptions?`): `Promise`\<[`GlobalPostageBatch`](../interfaces/GlobalPostageBatch.md)\> + +Defined in: [bee-js/src/modules/stamp.ts:187](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L187) + +Returns details for a specific globally available postage batch. + +#### Parameters + +##### postageBatchId + +Batch ID + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`GlobalPostageBatch`](../interfaces/GlobalPostageBatch.md)\> + +*** + +### topUp() + +> **topUp**(`postageBatchId`, `amount`, `requestOptions?`): `Promise`\<[`BatchId`](../classes/BatchId.md)\> + +Defined in: [bee-js/src/modules/stamp.ts:128](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L128) + +Increases the duration of a postage batch by increasing its amount. + +#### Parameters + +##### postageBatchId + +Batch ID + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### amount + +Amount to be added to the batch + +`string` | `bigint` | [`NumberString`](../type-aliases/NumberString.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BatchId`](../classes/BatchId.md)\> + +*** + +### updateLabel() + +> **updateLabel**(`postageBatchId`, `label`, `requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/stamp.ts:91](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/stamp.ts#L91) + +Updates the label of a certain postage batch. + +#### Parameters + +##### postageBatchId + +Batch ID of the postage batch to update. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### label + +`string` + +New label for the postage batch. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> diff --git a/docs/api/classes/Status.md b/docs/api/classes/Status.md new file mode 100644 index 00000000..1f4b1959 --- /dev/null +++ b/docs/api/classes/Status.md @@ -0,0 +1,226 @@ +# Class: Status + +Defined in: [bee-js/src/modules/status.ts:13](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L13) + +Node status, health, version and chain/reserve state operations. + +Accessed as `bee.status`. + +## Constructors + +### Constructor + +> **new Status**(`context`): `Status` + +Defined in: [bee-js/src/modules/status.ts:14](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L14) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Status` + +## Methods + +### get() + +> **get**(`requestOptions?`): `Promise`\<[`DebugStatus`](../interfaces/DebugStatus.md)\> + +Defined in: [bee-js/src/modules/status.ts:21](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L21) + +Gets the general status of the node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`DebugStatus`](../interfaces/DebugStatus.md)\> + +*** + +### getChainState() + +> **getChainState**(`requestOptions?`): `Promise`\<[`ChainState`](../interfaces/ChainState.md)\> + +Defined in: [bee-js/src/modules/status.ts:107](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L107) + +Gets chain state. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`ChainState`](../interfaces/ChainState.md)\> + +*** + +### getHealth() + +> **getHealth**(`requestOptions?`): `Promise`\<[`Health`](../interfaces/Health.md)\> + +Defined in: [bee-js/src/modules/status.ts:30](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L30) + +Gets the health of the node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Health`](../interfaces/Health.md)\> + +*** + +### getNodeInfo() + +> **getNodeInfo**(`requestOptions?`): `Promise`\<[`NodeInfo`](../interfaces/NodeInfo.md)\> + +Defined in: [bee-js/src/modules/status.ts:48](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L48) + +Gets mode information of the node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`NodeInfo`](../interfaces/NodeInfo.md)\> + +*** + +### getReadiness() + +> **getReadiness**(`requestOptions?`): `Promise`\<[`Readiness`](../interfaces/Readiness.md)\> + +Defined in: [bee-js/src/modules/status.ts:39](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L39) + +Gets the readiness status of the node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Readiness`](../interfaces/Readiness.md)\> + +*** + +### getReserveState() + +> **getReserveState**(`requestOptions?`): `Promise`\<[`ReserveState`](../interfaces/ReserveState.md)\> + +Defined in: [bee-js/src/modules/status.ts:98](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L98) + +Gets reserve state. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`ReserveState`](../interfaces/ReserveState.md)\> + +*** + +### getVersions() + +> **getVersions**(`requestOptions?`): `Promise`\<[`BeeVersions`](../interfaces/BeeVersions.md)\> + +Defined in: [bee-js/src/modules/status.ts:82](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L82) + +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*`). + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BeeVersions`](../interfaces/BeeVersions.md)\> + +*** + +### isSupportedApiVersion() + +> **isSupportedApiVersion**(`requestOptions?`): `Promise`\<`boolean`\> + +Defined in: [bee-js/src/modules/status.ts:70](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L70) + +Connects to a node and checks if its Main API version matches with the one that bee-js supports. + +This should be the main way how to check compatibility for your app and Bee node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`boolean`\> + +*** + +### isSupportedExactVersion() + +> **isSupportedExactVersion**(`requestOptions?`): `Promise`\<`boolean`\> + +Defined in: [bee-js/src/modules/status.ts:57](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/status.ts#L57) + +Connects to a node and checks if its version matches with the one that bee-js supports. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`boolean`\> diff --git a/docs/api/classes/Storage.md b/docs/api/classes/Storage.md new file mode 100644 index 00000000..02cfd3ea --- /dev/null +++ b/docs/api/classes/Storage.md @@ -0,0 +1,401 @@ +# Class: Storage + +Defined in: [bee-js/src/modules/storage.ts:16](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L16) + +Ergonomic storage operations expressed in terms of size and duration. + +Accessed as `bee.storage`. Wraps the low-level `bee.stamp` operations. + +## Constructors + +### Constructor + +> **new Storage**(`context`): `Storage` + +Defined in: [bee-js/src/modules/storage.ts:17](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L17) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Storage` + +## Methods + +### buy() + +> **buy**(`size`, `duration`, `options?`, `requestOptions?`, `encryption?`, `erasureCodeLevel?`): `Promise`\<[`BatchId`](../classes/BatchId.md)\> + +Defined in: [bee-js/src/modules/storage.ts:35](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L35) + +Creates a postage batch sized for a certain size and duration on the Swarm network. + +Use [getCost](#getcost) to calculate the cost beforehand. + +#### Parameters + +##### size + +[`Size`](../classes/Size.md) + +##### duration + +[`Duration`](../classes/Duration.md) + +##### options? + +[`PostageBatchOptions`](../interfaces/PostageBatchOptions.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +##### encryption? + +`boolean` + +##### erasureCodeLevel? + +[`RedundancyLevel`](../enumerations/RedundancyLevel.md) + +#### Returns + +`Promise`\<[`BatchId`](../classes/BatchId.md)\> + +*** + +### extend() + +> **extend**(`postageBatchId`, `size`, `duration`, `requestOptions?`, `encryption?`, `erasureCodeLevel?`): `Promise`\<[`BatchId`](../classes/BatchId.md) \| [`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/storage.ts:89](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L89) + +Extends the storage of a postage batch by either increasing its size, duration or both. + +The size is ABSOLUTE, while the duration is RELATIVE to the current duration of the postage batch. + +#### Parameters + +##### postageBatchId + +Batch ID of the postage batch to extend. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### size + +[`Size`](../classes/Size.md) + +Absolute size to extend the postage batch to. + +##### duration + +[`Duration`](../classes/Duration.md) + +Relative duration to extend the postage batch by. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +##### encryption? + +`boolean` + +Assume the future uploaded data is encrypted, which skews the capacity of the postage batch. + +##### erasureCodeLevel? + +[`RedundancyLevel`](../enumerations/RedundancyLevel.md) + +Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch. + +#### Returns + +`Promise`\<[`BatchId`](../classes/BatchId.md) \| [`TransactionId`](../classes/TransactionId.md)\> + +*** + +### extendDuration() + +> **extendDuration**(`postageBatchId`, `duration`, `requestOptions?`): `Promise`\<[`BatchId`](../classes/BatchId.md)\> + +Defined in: [bee-js/src/modules/storage.ts:165](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L165) + +Extends the duration of a postage batch. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### duration + +[`Duration`](../classes/Duration.md) + +Relative duration to extend the postage batch by. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BatchId`](../classes/BatchId.md)\> + +*** + +### extendSize() + +> **extendSize**(`postageBatchId`, `size`, `requestOptions?`, `encryption?`, `erasureCodeLevel?`): `Promise`\<[`BatchId`](../classes/BatchId.md)\> + +Defined in: [bee-js/src/modules/storage.ts:136](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L136) + +Extends the storage size of a postage batch by increasing its depth. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### size + +[`Size`](../classes/Size.md) + +Absolute size to extend the postage batch to. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +##### encryption? + +`boolean` + +Assume the future uploaded data is encrypted, which skews the capacity of the postage batch. + +##### erasureCodeLevel? + +[`RedundancyLevel`](../enumerations/RedundancyLevel.md) + +Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch. + +#### Returns + +`Promise`\<[`BatchId`](../classes/BatchId.md)\> + +*** + +### getCost() + +> **getCost**(`size`, `duration`, `requestOptions?`, `encryption?`, `erasureCodeLevel?`): `Promise`\<[`BZZ`](../classes/BZZ.md)\> + +Defined in: [bee-js/src/modules/storage.ts:63](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L63) + +Calculates the estimated BZZ cost for creating a postage batch for the given size and duration. + +#### Parameters + +##### size + +[`Size`](../classes/Size.md) + +Size of the data to be stored. + +##### duration + +[`Duration`](../classes/Duration.md) + +Duration for which the data should be stored. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +##### encryption? + +`boolean` + +Assume the future uploaded data is encrypted, which skews the capacity of the postage batch. + +##### erasureCodeLevel? + +[`RedundancyLevel`](../enumerations/RedundancyLevel.md) + +Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch. + +#### Returns + +`Promise`\<[`BZZ`](../classes/BZZ.md)\> + +*** + +### getDurationExtensionCost() + +> **getDurationExtensionCost**(`postageBatchId`, `duration`, `requestOptions?`): `Promise`\<[`BZZ`](../classes/BZZ.md)\> + +Defined in: [bee-js/src/modules/storage.ts:246](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L246) + +Calculates the cost of extending the duration of a postage batch. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### duration + +[`Duration`](../classes/Duration.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`BZZ`](../classes/BZZ.md)\> + +*** + +### getExtensionCost() + +> **getExtensionCost**(`postageBatchId`, `size`, `duration`, `requestOptions?`, `encryption?`, `erasureCodeLevel?`): `Promise`\<[`BZZ`](../classes/BZZ.md)\> + +Defined in: [bee-js/src/modules/storage.ts:187](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L187) + +Calculates the cost of extending both the duration and the capacity of a postage batch. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### size + +[`Size`](../classes/Size.md) + +Absolute size to extend the postage batch to. + +##### duration + +[`Duration`](../classes/Duration.md) + +Relative duration to extend the postage batch by. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +##### encryption? + +`boolean` + +Assume the future uploaded data is encrypted, which skews the capacity of the postage batch. + +##### erasureCodeLevel? + +[`RedundancyLevel`](../enumerations/RedundancyLevel.md) + +Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch. + +#### Returns + +`Promise`\<[`BZZ`](../classes/BZZ.md)\> + +*** + +### getSizeExtensionCost() + +> **getSizeExtensionCost**(`postageBatchId`, `size`, `requestOptions?`, `encryption?`, `erasureCodeLevel?`): `Promise`\<[`BZZ`](../classes/BZZ.md)\> + +Defined in: [bee-js/src/modules/storage.ts:216](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L216) + +Calculates the cost of extending the size of a postage batch. + +#### Parameters + +##### postageBatchId + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### size + +[`Size`](../classes/Size.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +##### encryption? + +`boolean` + +Assume the future uploaded data is encrypted, which skews the capacity of the postage batch. + +##### erasureCodeLevel? + +[`RedundancyLevel`](../enumerations/RedundancyLevel.md) + +Assume the future uploaded data is erasure coded, which skews the capacity of the postage batch. + +#### Returns + +`Promise`\<[`BZZ`](../classes/BZZ.md)\> + +*** + +### rename() + +> **rename**(`postageBatchId`, `newLabel`, `requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/storage.ts:265](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/storage.ts#L265) + +Renames a storage. Convenience wrapper over `bee.stamp.updateLabel`. + +#### Parameters + +##### postageBatchId + +Batch ID of the postage batch to update. + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`BatchId`](../classes/BatchId.md) + +##### newLabel + +`string` + +New name for the storage. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> diff --git a/docs/api/classes/Tag.md b/docs/api/classes/Tag.md new file mode 100644 index 00000000..ff17a5b3 --- /dev/null +++ b/docs/api/classes/Tag.md @@ -0,0 +1,165 @@ +# Class: Tag + +Defined in: [bee-js/src/modules/tag.ts:13](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/tag.ts#L13) + +Tag operations for tracking upload and synchronization progress. + +Accessed as `bee.tag`. + +## Constructors + +### Constructor + +> **new Tag**(`context`): `Tag` + +Defined in: [bee-js/src/modules/tag.ts:14](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/tag.ts#L14) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Tag` + +## Methods + +### create() + +> **create**(`requestOptions?`): `Promise`\<[`Tag`](../interfaces/Tag.md)\> + +Defined in: [bee-js/src/modules/tag.ts:21](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/tag.ts#L21) + +Creates a new tag which is meant for tracking upload and synchronization progress. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Tag`](../interfaces/Tag.md)\> + +*** + +### delete() + +> **delete**(`tagUid`, `requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/tag.ts:57](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/tag.ts#L57) + +Deletes a tag. + +#### Parameters + +##### tagUid + +UID or tag object to be deleted + +`number` | [`Tag`](../interfaces/Tag.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> + +*** + +### get() + +> **get**(`tagUid`, `requestOptions?`): `Promise`\<[`Tag`](../interfaces/Tag.md)\> + +Defined in: [bee-js/src/modules/tag.ts:45](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/tag.ts#L45) + +Retrieves tag information from the Bee node. + +#### Parameters + +##### tagUid + +UID or tag object to be retrieved + +`number` | [`Tag`](../interfaces/Tag.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Tag`](../interfaces/Tag.md)\> + +*** + +### getAll() + +> **getAll**(`options?`, `requestOptions?`): `Promise`\<[`Tag`](../interfaces/Tag.md)[]\> + +Defined in: [bee-js/src/modules/tag.ts:31](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/tag.ts#L31) + +Fetches all tags in a paginated manner. + +#### Parameters + +##### options? + +[`AllTagsOptions`](../interfaces/AllTagsOptions.md) + +Specify `limit` and `offset` to paginate through the tags. + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`Tag`](../interfaces/Tag.md)[]\> + +*** + +### update() + +> **update**(`tagUid`, `reference`, `requestOptions?`): `Promise`\<`void`\> + +Defined in: [bee-js/src/modules/tag.ts:70](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/tag.ts#L70) + +Updates a tag's total chunks count. + +#### Parameters + +##### tagUid + +UID or tag object to be updated + +`number` | [`Tag`](../interfaces/Tag.md) + +##### reference + +The root reference that contains all the chunks to be counted + +`string` | [`Reference`](../classes/Reference.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<`void`\> diff --git a/docs/api/classes/Transaction.md b/docs/api/classes/Transaction.md new file mode 100644 index 00000000..1e102acf --- /dev/null +++ b/docs/api/classes/Transaction.md @@ -0,0 +1,139 @@ +# Class: Transaction + +Defined in: [bee-js/src/modules/transaction.ts:12](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/transaction.ts#L12) + +Pending transaction operations for the Bee node's `/transactions` queue. + +Accessed as `bee.transaction`. + +## Constructors + +### Constructor + +> **new Transaction**(`context`): `Transaction` + +Defined in: [bee-js/src/modules/transaction.ts:13](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/transaction.ts#L13) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Transaction` + +## Methods + +### cancel() + +> **cancel**(`transactionHash`, `gasPrice?`, `requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/transaction.ts:63](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/transaction.ts#L63) + +Cancels a currently pending transaction. + +#### Parameters + +##### transactionHash + +Hash of the transaction + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`TransactionId`](../classes/TransactionId.md) + +##### gasPrice? + +Optional gas price + +`string` | `bigint` | [`NumberString`](../type-aliases/NumberString.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +*** + +### get() + +> **get**(`transactionHash`, `requestOptions?`): `Promise`\<[`TransactionInfo`](../interfaces/TransactionInfo.md)\> + +Defined in: [bee-js/src/modules/transaction.ts:30](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/transaction.ts#L30) + +Fetches the transaction information for a specific pending transaction. + +#### Parameters + +##### transactionHash + +Hash of the transaction + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`TransactionId`](../classes/TransactionId.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionInfo`](../interfaces/TransactionInfo.md)\> + +*** + +### getAll() + +> **getAll**(`requestOptions?`): `Promise`\<[`TransactionInfo`](../interfaces/TransactionInfo.md)[]\> + +Defined in: [bee-js/src/modules/transaction.ts:20](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/transaction.ts#L20) + +Fetches the list of all current pending transactions for the Bee node. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionInfo`](../interfaces/TransactionInfo.md)[]\> + +*** + +### rebroadcast() + +> **rebroadcast**(`transactionHash`, `requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/transaction.ts:47](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/transaction.ts#L47) + +Rebroadcasts an already created pending transaction. + +Mainly needed when the transaction falls off the mempool or is not incorporated into any block. + +#### Parameters + +##### transactionHash + +Hash of the transaction + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`TransactionId`](../classes/TransactionId.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> diff --git a/docs/api/classes/Wallet.md b/docs/api/classes/Wallet.md new file mode 100644 index 00000000..859007f8 --- /dev/null +++ b/docs/api/classes/Wallet.md @@ -0,0 +1,111 @@ +# Class: Wallet + +Defined in: [bee-js/src/modules/wallet.ts:12](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/wallet.ts#L12) + +Node wallet operations (balances and external withdrawals). + +Accessed as `bee.wallet`. + +## Constructors + +### Constructor + +> **new Wallet**(`context`): `Wallet` + +Defined in: [bee-js/src/modules/wallet.ts:13](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/wallet.ts#L13) + +#### Parameters + +##### context + +`BeeContext` + +#### Returns + +`Wallet` + +## Methods + +### getBalance() + +> **getBalance**(`requestOptions?`): `Promise`\<[`WalletBalance`](../interfaces/WalletBalance.md)\> + +Defined in: [bee-js/src/modules/wallet.ts:20](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/wallet.ts#L20) + +Gets DAI and BZZ balances of the Bee node wallet. + +#### Parameters + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`WalletBalance`](../interfaces/WalletBalance.md)\> + +*** + +### withdrawBZZ() + +> **withdrawBZZ**(`amount`, `address`, `requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/wallet.ts:31](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/wallet.ts#L31) + +Withdraws BZZ from the node wallet (not chequebook) to a whitelisted external wallet address. + +#### Parameters + +##### amount + +Amount of BZZ tokens to withdraw. If not providing a `BZZ` instance, the amount is denoted in PLUR. + +`string` | `bigint` | [`BZZ`](../classes/BZZ.md) | [`NumberString`](../type-aliases/NumberString.md) + +##### address + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`EthAddress`](../classes/EthAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +*** + +### withdrawDAI() + +> **withdrawDAI**(`amount`, `address`, `requestOptions?`): `Promise`\<[`TransactionId`](../classes/TransactionId.md)\> + +Defined in: [bee-js/src/modules/wallet.ts:49](https://github.com/ethersphere/bee-js/blob/bab2b2e5a3874187d29a1c1e6c70f2f645ed53c2/src/modules/wallet.ts#L49) + +Withdraws DAI from the node wallet (not chequebook) to a whitelisted external wallet address. + +#### Parameters + +##### amount + +Amount of DAI tokens to withdraw. If not providing a `DAI` instance, the amount is denoted in wei. + +`string` | `bigint` | [`NumberString`](../type-aliases/NumberString.md) | [`DAI`](../classes/DAI.md) + +##### address + +`string` | `Uint8Array`\<`ArrayBufferLike`\> | [`EthAddress`](../classes/EthAddress.md) + +##### requestOptions? + +[`BeeRequestOptions`](../type-aliases/BeeRequestOptions.md) + +Options for making requests, such as timeouts, custom HTTP agents, headers, etc. + +#### Returns + +`Promise`\<[`TransactionId`](../classes/TransactionId.md)\> diff --git a/docs/documentation/overview.md b/docs/documentation/overview.md index 0194a9c0..21379916 100644 --- a/docs/documentation/overview.md +++ b/docs/documentation/overview.md @@ -35,27 +35,27 @@ Operations on the `Bee` class are grouped into namespaces by subject. Instead of | Namespace | Purpose | | --------- | ------- | -| `bee.data` | Raw data uploads and downloads, backed by `/bytes`. | -| `bee.file` | Single-file uploads and downloads, backed by `/bzz`. | -| `bee.collection` | Multi-file (directory) uploads, backed by `/bzz`. | -| `bee.chunk` | Individual chunk uploads and downloads, backed by `/chunks`. | -| `bee.feed` | Feed readers, writers and manifests. | -| `bee.soc` | Single owner chunk readers and writers. | -| `bee.messaging` | PSS and GSOC messaging. | -| `bee.stamp` | Postage batches expressed in amount and depth. | -| `bee.storage` | Postage batches expressed in size and duration. | -| `bee.tag` | Tags for tracking upload progress. | -| `bee.pin` | Local pinning and reuploading. | -| `bee.grantee` | Access control (ACT) grantee lists. | -| `bee.stake` | Staking and the redistribution game. | -| `bee.status` | Node health, version, chain and reserve state. | -| `bee.connectivity` | Peers, topology and node addresses. | -| `bee.wallet` | Node wallet balances and external withdrawals. | -| `bee.chequebook` | Chequebook address, balance, deposits and withdrawals. | -| `bee.cheque` | Cheques and cashouts. | -| `bee.balance` | SWAP balances with peers. | -| `bee.settlement` | SWAP settlements with peers. | -| `bee.transaction` | The node's pending transaction queue. | +| [`bee.data`](../api/classes/Data.md) | Raw data uploads and downloads, backed by `/bytes`. | +| [`bee.file`](../api/classes/File.md) | Single-file uploads and downloads, backed by `/bzz`. | +| [`bee.collection`](../api/classes/Collection.md) | Multi-file (directory) uploads, backed by `/bzz`. | +| [`bee.chunk`](../api/classes/Chunk.md) | Individual chunk uploads and downloads, backed by `/chunks`. | +| [`bee.feed`](../api/classes/Feed.md) | Feed readers, writers and manifests. | +| [`bee.soc`](../api/classes/Soc.md) | Single owner chunk readers and writers. | +| [`bee.messaging`](../api/classes/Messaging.md) | PSS and GSOC messaging. | +| [`bee.stamp`](../api/classes/Stamp.md) | Postage batches expressed in amount and depth. | +| [`bee.storage`](../api/classes/Storage.md) | Postage batches expressed in size and duration. | +| [`bee.tag`](../api/classes/Tag.md) | Tags for tracking upload progress. | +| [`bee.pin`](../api/classes/Pin.md) | Local pinning and reuploading. | +| [`bee.grantee`](../api/classes/Grantee.md) | Access control (ACT) grantee lists. | +| [`bee.stake`](../api/classes/Stake.md) | Staking and the redistribution game. | +| [`bee.status`](../api/classes/Status.md) | Node health, version, chain and reserve state. | +| [`bee.connectivity`](../api/classes/Connectivity.md) | Peers, topology and node addresses. | +| [`bee.wallet`](../api/classes/Wallet.md) | Node wallet balances and external withdrawals. | +| [`bee.chequebook`](../api/classes/Chequebook.md) | Chequebook address, balance, deposits and withdrawals. | +| [`bee.cheque`](../api/classes/Cheque.md) | Cheques and cashouts. | +| [`bee.balance`](../api/classes/Balance.md) | SWAP balances with peers. | +| [`bee.settlement`](../api/classes/Settlement.md) | SWAP settlements with peers. | +| [`bee.transaction`](../api/classes/Transaction.md) | The node's pending transaction queue. | A handful of methods stay directly on `bee` because they do not belong to any one subject: `makeContentAddressedChunk`, `unmarshalContentAddressedChunk`, `makeSingleOwnerChunk`, `unmarshalSingleOwnerChunk`, `calculateSingleOwnerChunkAddress`, `createEnvelope` and `rchash`. diff --git a/scripts/generate-api.mjs b/scripts/generate-api.mjs index 30cfbfc9..0929d7fb 100644 --- a/scripts/generate-api.mjs +++ b/scripts/generate-api.mjs @@ -20,7 +20,7 @@ // plugin upgrade rewrites unrelated pages. Upgrade them deliberately, on their own. import { execFileSync } from 'node:child_process'; -import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'; +import { existsSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -28,22 +28,26 @@ const __dirname = dirname(fileURLToPath(import.meta.url)); const ROOT = join(__dirname, '..'); const API_DIR = join(ROOT, 'docs', 'api'); -// typedoc renders the project index as a README, and nests the one namespace it -// finds under a directory named after the package. -const PACKAGE_DIR = join(API_DIR, '@ethersphere'); -const RAW_UTILS_DIR = join(PACKAGE_DIR, 'namespaces', 'Utils'); +// typedoc renders one module per entry point, nested under a directory named +// after that entry point's path. The main entry point's pages therefore arrive +// under bee-js/src, and each namespace class under bee-js/src/modules/. +const ENTRY_DIR = join(API_DIR, 'bee-js', 'src'); +const MODULES_DIR = join(API_DIR, 'modules'); +const CLASSES_DIR = join(API_DIR, 'classes'); const UTILS_DIR = join(API_DIR, 'namespaces', 'Utils'); -const OVERVIEW_FRONTMATTER = ['id: Overview', 'title: Overview', 'slug: /api/', 'sidebar_position: 0']; +/** + * Rewrite the `../` prefixes of a page's relative links after the page moves + * `levels` closer to docs/api. + */ +function liftLinks(content, levels) { + return content.replace(/\]\(((?:\.\.\/)+)/g, (_match, ups) => { + const depth = ups.length / '../'.length; + return `](${'../'.repeat(Math.max(depth - levels, 0))}`; + }); +} -// Hand-written: typedoc has no way to know that the classes behind the Bee -// namespaces are missing. They live in src/modules/*.ts, are not exported from -// src/index.ts, and cannot be added as entry points because their names collide -// with exported types (Data, Tag, Pin, Collection, Cheque, Chunk). They are -// documented by hand in docs/documentation/overview.md instead. -const OVERVIEW_ADMONITION = `:::info Namespace methods -This reference covers everything \`@ethersphere/bee-js\` exports. The classes behind \`bee.data\`, \`bee.file\`, \`bee.stamp\` and the other [namespaces](../documentation/overview.md#namespaces) are internal to the library and have no page of their own here. The [SDK Overview](../documentation/overview.md#bee-api) lists every namespaced method together with the Bee endpoint it calls. -:::`; +const OVERVIEW_FRONTMATTER = ['id: Overview', 'title: Overview', 'slug: /api/', 'sidebar_position: 0']; function* markdownFiles(dir) { for (const entry of readdirSync(dir, { withFileTypes: true })) { @@ -78,45 +82,109 @@ execFileSync(process.execPath, [join(ROOT, 'node_modules', 'typedoc', 'bin', 'ty stdio: 'inherit', }); +// ── Lift the main entry point to the top ──────────────────────────── + +// Everything the site publishes lives under the bee-js/src module directory, +// so the whole subtree moves up to docs/api. Because it moves as one piece, the +// relative links inside it stay correct without any rewriting. +if (!existsSync(ENTRY_DIR)) { + fail(`Expected the main entry point at ${relative(ROOT, ENTRY_DIR)}. Has the typedoc layout changed?`); +} + +// The index typedoc writes at the top is the list of entry points, which is a +// list of source paths and of no use to a reader. The index worth keeping is +// the one inside the entry point directory, and it takes this name. +rmSync(join(API_DIR, 'README.md'), { force: true }); + +for (const entry of readdirSync(ENTRY_DIR)) { + renameSync(join(ENTRY_DIR, entry), join(API_DIR, entry)); +} +rmSync(join(API_DIR, 'bee-js'), { recursive: true, force: true }); + // ── Flatten the Utils namespace ───────────────────────────────────── -// The namespace pages are the only ones typedoc buries under a package -// directory and a `functions` directory. Lifting them to namespaces/Utils -// keeps the URLs short and the sidebar flat, which costs two directory levels -// off every relative link they contain. -const functionsDir = join(RAW_UTILS_DIR, 'functions'); +// Utils is the one namespace typedoc buries under a `functions` directory. +// Lifting its pages to namespaces/Utils keeps the URLs short and the sidebar +// flat, which costs one directory level off every relative link they contain. +const functionsDir = join(UTILS_DIR, 'functions'); if (!existsSync(functionsDir)) { fail(`Expected the Utils namespace at ${relative(ROOT, functionsDir)}. Has the typedoc layout changed?`); } -mkdirSync(UTILS_DIR, { recursive: true }); const utilsPages = readdirSync(functionsDir).filter(name => name.endsWith('.md')).sort(); for (const name of utilsPages) { const source = join(functionsDir, name); - const content = readFileSync(source, 'utf-8').replace(/\]\(((?:\.\.\/)+)/g, (_match, ups) => { - const levels = ups.length / '../'.length; - return `](${'../'.repeat(Math.max(levels - 2, 0))}`; - }); - writeFileSync(join(UTILS_DIR, name), content); + writeFileSync(join(UTILS_DIR, name), liftLinks(readFileSync(source, 'utf-8'), 1)); rmSync(source); } // The namespace's own index page is dropped: the sidebar links straight to the // function pages, so nothing points at it. -rmSync(PACKAGE_DIR, { recursive: true, force: true }); +rmSync(functionsDir, { recursive: true, force: true }); +rmSync(join(UTILS_DIR, 'README.md'), { force: true }); console.log(`Moved ${utilsPages.length} Utils page(s) to ${relative(ROOT, UTILS_DIR)}`); +// ── Flatten the namespace classes ─────────────────────────────────── + +// Each namespace class is its own entry point, so each one arrives alone in a +// modules//classes directory. They are classes like any other, so they +// join the rest in docs/api/classes — two directory levels shallower — and the +// sidebar picks them up with no configuration of its own. None of their names +// collide with a page already there. +if (!existsSync(MODULES_DIR)) { + fail(`Expected the namespace classes under ${relative(ROOT, MODULES_DIR)}. Has the typedoc layout changed?`); +} + +const namespaceClasses = []; + +for (const moduleName of readdirSync(MODULES_DIR).sort()) { + const classesDir = join(MODULES_DIR, moduleName, 'classes'); + if (!existsSync(classesDir)) { + fail(`The ${moduleName} module produced no class page. Is src/modules/${moduleName}.ts still a namespace class?`); + } + + for (const name of readdirSync(classesDir).filter(entry => entry.endsWith('.md'))) { + writeFileSync(join(CLASSES_DIR, name), liftLinks(readFileSync(join(classesDir, name), 'utf-8'), 2)); + namespaceClasses.push(name.replace(/\.md$/, '')); + } +} + +// The per-module index pages go with the directory: each held a single link to +// a class page that now sits next to the other classes. +rmSync(MODULES_DIR, { recursive: true, force: true }); + +// Bee.md is the only page that links into the layout just dismantled — it is +// where the namespaces are reachable from, one property per class. +const beePage = join(CLASSES_DIR, 'Bee.md'); +const beeLinked = readFileSync(beePage, 'utf-8').replace(/\]\(\.\.\/modules\/[^/]+\/classes\/([^/)]+\.md)\)/g, ']($1)'); +writeFileSync(beePage, beeLinked); +console.log(`Moved ${namespaceClasses.length} namespace class page(s) to ${relative(ROOT, CLASSES_DIR)}`); + // ── Turn the index into Overview.md ───────────────────────────────── const readme = join(API_DIR, 'README.md'); if (!existsSync(readme)) fail('typedoc produced no README.md to turn into Overview.md.'); -const overview = readFileSync(readme, 'utf-8') - .replace(/^# .*\n+/, '') // the package name is what the frontmatter title replaces - .replace(/^- \[Utils\]\(.*\)$/m, `- [Utils](./namespaces/Utils/${utilsPages[0].replace(/\.md$/, '')}.md)`); +// The namespace classes came from entry points of their own, so this index has +// never heard of them. They are folded into the class list it already carries, +// in the same case-insensitive order typedoc sorts it by. +function withNamespaceClasses(index) { + return index.replace(/(## Classes\n\n)((?:- .*\n)+)/, (_match, heading, list) => { + const entries = [...list.trimEnd().split('\n'), ...namespaceClasses.map(name => `- [${name}](classes/${name}.md)`)]; + entries.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())); + + return `${heading}${entries.join('\n')}\n`; + }); +} + +const overview = withNamespaceClasses( + readFileSync(readme, 'utf-8') + .replace(/^# .*\n+/, '') // the entry point path is what the frontmatter title replaces + .replace(/^- \[Utils\]\(.*\)$/m, `- [Utils](./namespaces/Utils/${utilsPages[0].replace(/\.md$/, '')}.md)`), +); -writeFileSync(join(API_DIR, 'Overview.md'), `---\n${OVERVIEW_FRONTMATTER.join('\n')}\n---\n\n${OVERVIEW_ADMONITION}\n\n${overview}`); +writeFileSync(join(API_DIR, 'Overview.md'), `---\n${OVERVIEW_FRONTMATTER.join('\n')}\n---\n\n${overview}`); rmSync(readme); console.log('Wrote docs/api/Overview.md'); diff --git a/typedoc.config.mjs b/typedoc.config.mjs index 7f5c76a5..e13348b5 100644 --- a/typedoc.config.mjs +++ b/typedoc.config.mjs @@ -8,7 +8,17 @@ /** @type {import('typedoc').TypeDocOptions} */ export default { - entryPoints: ['sources/bee-js/src/index.ts'], + // The namespace classes behind `bee.data`, `bee.wallet` and friends are not + // exported from src/index.ts, so typedoc only ever sees them as the unlinkable + // type of a `Bee` property. Adding them as entry points of their own is what + // gives them pages; their names collide with exported types (Data, Tag, Pin, + // Collection, Chunk), which is harmless here because each entry point is its + // own module. generate-api.mjs folds the result back into docs/api/classes. + entryPoints: ['sources/bee-js/src/index.ts', 'sources/bee-js/src/modules/*.ts'], + + // The context facade is internal plumbing: every namespace class takes one in + // its constructor, but no caller ever builds one. + exclude: ['**/modules/context.ts'], tsconfig: 'sources/bee-js/tsconfig.json', plugin: ['typedoc-plugin-markdown', './scripts/typedoc-frontmatter-titles.mjs'], out: 'docs/api',