feat: upcoming bee-js

Author: Ferenc Sárai

docs/user-documentation/act.md

@@ -21,33 +21,38 @@ We also need an instance of Bee to interact with the Bee node.
 
 ```ts
 import { Bee } from "@ethersphere/bee-js"
+```
 
-const bee = new Bee('http://localhost:1633')
+```ts
+const bee = new Bee('http://localhost:1633') // Use BeeDev if running Bee in dev mode locally
 ```
 
 ### Upload with ACT
 
-When uploading, we can specify that we are using ACT in the optional `requestOptions` of the `bee-js` `uploadData` method.
+When uploading, we can specify that we are using ACT in the optional `options: RedundantUploadOptions` of the `bee-js` `uploadData` method.
 
 ```ts
-const beeRequestOptionsUpload = {
-    act: true,
-}
-const uploadResultACT = await bee.uploadData(
-    postageBatchId,
-    "Bee is awesome with ACT!",
-    beeRequestOptionsUpload
-)
-console.log(uploadResultACT)
+const optionsUp = {
+  act: true,
+};
+const uploadResultACT: UploadResult = await bee.uploadData(
+  postageBatchId,
+  "Bee is awesome with ACT!",
+  optionsUp);
+console.log('uploadResultACT:', {
+    ...uploadResultACT,
+    reference: uploadResultACT.reference.toString(),
+    historyAddress: uploadResultACT.historyAddress.getOrThrow().toString()
+});
 ```
 
 The return value provides a `reference` and a `historyAddress`. Both will be needed for the download.
 
 ```json title="uploadResultACT"
 {
-  "reference": "97132e8e17831dfa220e73ee083bd82819aaeffce0aaf7e1e0abf8135fcfd2fc",
-  "tagUid": 14,
-  "historyAddress": "c6cabe3a3b7879ddb182277f3037c02002d4ce33280007cac580ac9256be20ea"
+  "reference": "85ae50e61155d4a0c9c4563c96074e16c33e5640bacfde1ce488978d602927fa",
+  "tagUid": 111,
+  "historyAddress": "97a1f10b344e79cde136353a61877b417af2c8ecea4a20a362b920aedb240dc7"
 }
 ```
 
@@ -57,30 +62,25 @@ During the upload process, the node performing the upload acts as the __publishe
 
 ### Download with ACT
 
-When downloading, we can specify that we are using __ACT__ in the optional `requestOptions` of the `bee-js` `downloadData` method.
+When downloading, we can specify that we are using __ACT__ in the optional `options: DownloadOptions` of the `bee-js` `downloadData` method.
 
 :::warning
 Downloading is only possible with the knowledge of the __publisher's__ public key.
 :::
 
 ```ts
-const addr = await bee.getNodeAddresses()
+const addr = await bee.getNodeAddresses();
 
 // node public key (publisher public key)
-const pubk = addr.publicKey
-
-const beeRequestOptionsDownload = {
-    baseURL: BEE_API_URL,
-    timeout: 0, // false converted to number
-    headers: {
-        'swarm-act': 'true',
-        'swarm-act-publisher': pubk, // publisher public key
-        'swarm-act-history-address': uploadResultACT.historyAddress,
-    },
-}
-
-const retrievedData = await bee.downloadData(uploadResultACT.reference, beeRequestOptionsDownload)
-console.log(await retrievedData.text()) // prints 'Bee is awesome with ACT!'
+const pubk = addr.publicKey;
+const optionsDown: DownloadOptions = {
+  actPublisher: pubk,
+  actHistoryAddress: uploadResultACT.historyAddress.getOrThrow(),
+  actTimestamp: 1
+};
+
+const retrievedData: Bytes = await bee.downloadData(uploadResultACT.reference, optionsDown);
+console.log('retrievedData:', retrievedData.toUtf8()); // prints 'Bee is awesome with ACT!'
 ```
 
 ### Create Grantees
@@ -89,38 +89,45 @@ To download from another node, we need to create a grantee list for the uploaded
 
 ```ts
 const granteePublicKeys = [
-    "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e8",
-    "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e9",
-    "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12ee"
-]
+  "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e8",
+  "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e9",
+  "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12ee"
+];
 
 // Create Grantees
-const granteeResult = await bee.createGrantees(postageBatchId, granteePublicKeys)
-console.log(granteeResult)
+const granteesResult: GranteesResult  = await bee.createGrantees(postageBatchId, granteePublicKeys);
+console.log('granteesResult:', {
+  ...granteesResult,
+  ref: granteesResult.ref.toString(),
+  historyref: granteesResult.historyref.toString(),
+})
 ```
 
 ```json title="granteeResult"
 {
   "status": 201,
   "statusText": "Created",
-  "ref": "810b802516f3f0d1ded180d19fdf27bbc05b95a5b7ec8448b5a2d90819e06bed8fdf0697efad7074e66f52679a3aa51010d1897f4ce00918f8fd938b0ff35c3a",
-  "historyref": "4feb7fc56dcea1acaa74c1fb980156d6db9667b223809c082d69542545c67faf"
+  "ref": "30f7ba4fec333227dac0053114f68e70ee64290e095d99470a074fa687f0ad0774370a1e597447fbec7f916c4a2f70d0719150dce3573b290b3fcfe7883ed79d",
+  "historyref": "81cd33bf01b771ed899cb41f4d5e91b49dc28a42ee28144f8ba1ba59ecc66f09"
 }
 ```
 
 ### List Grantees
 
 ```ts
 // List Grantees
-const getGranteesResult = await bee.getGrantees(granteeResult.ref)
-console.log(getGranteesResult)
+const getGranteesResult: GetGranteesResult = await bee.getGrantees(granteesResult.ref);
+console.log('getGranteesResult:', {
+  ...getGranteesResult,
+   grantees: getGranteesResult.grantees.map(grantee => grantee.toCompressedHex())
+});
 ```
 
 ```json title="getGranteesResult"
 {
   "status": 200,
   "statusText": "OK",
-  "data": [
+  "grantees": [
     "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e8",
     "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e9",
     "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12ee"
@@ -144,40 +151,41 @@ const patchGrantees = {
     ]
 }
 // A short delay is needed if we call it immediately after createGrantees.
-await new Promise(resolve => setTimeout(resolve, 1500))
-const granteeResultAfterPatch = await bee.patchGrantees(
-    postageBatchId,
-    granteeResult.ref,
-    granteeResult.historyref,
-    patchGrantees
-)
-console.log(granteeResultAfterPatch)
+await new Promise(resolve => setTimeout(resolve, 1500));
+const granteeResultAfterPatch: GranteesResult = await bee.patchGrantees(postageBatchId, granteesResult.ref, granteesResult.historyref, patch_grantees);
+console.log('granteeResultAfterPatch:', {
+    ...granteeResultAfterPatch,
+    ref: granteeResultAfterPatch.ref.toString(),
+    historyref: granteeResultAfterPatch.historyref.toString(),
+})
 ```
 
 ```json title="granteeResultAfterPatch"
 {
   "status": 200,
   "statusText": "OK",
-  "ref": "ae9fd8e0d9158ab9a433bacfde9109bd0545e31a0d8e4f592a5a558e842de59a86f73e08a594874fe38d6a68cfa636a729dcc73b746083b12a384b6578ac5dce",
-  "historyref": "0a0f709ed9d5ecd46434b8c62aeefc84bffeed7a80741c453d27ffdf67359fff"
+  "ref": "694152dd351a701a0090b82bbdbd892f110a589596f6a504833855af91aacbf127e292a8a49119c53ec46c112501eab6933340c59d05576ec45354e990479e5f",
+  "historyref": "73a62da4ad3a29f1899b548d3dbe1a96baab11ab73b02e36ce9fec728a5b87d3"
 }
 ```
 
 After the patch, the grantee list will have a new reference.
 
 ```ts
-// List Grantees
-const getGranteesResultAfterPatch = await bee.getGrantees(granteeResultAfterPatch.ref)
-console.log(getGranteesResultAfterPatch)
+const getGranteesResultAfterPatch: GetGranteesResult = await bee.getGrantees(granteeResultAfterPatch.ref);
+console.log('getGranteesResultAfterPatch:', {
+    ...getGranteesResultAfterPatch,
+    grantees: getGranteesResultAfterPatch.grantees.map(grantee => grantee.toCompressedHex())
+});
 ```
 
 ```json title="getGranteesResultAfterPatch"
 {
   "status": 200,
   "statusText": "OK",
-  "data": [
+  "grantees": [
     "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e8",
-    "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e7"
+    "02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e7"'
   ]
 }
 ```