feat!: add act (#942)

* feat(act): add act

* feat(act): rename addGrantees to createGrantees

* feat(act): remove mention of ENS name in getGrantees method comment

* feat(act): add grantee module for managing grantees

* feat(act): revert import chai and jestExpect in bzz.spec.ts

* feat(act): improve documentation for the createGrantees method

* feat(act)!: update the return type of chunk upload to UploadResult from Reference

* feat(act)!: update the return type of soc upload to UploadResult from Reference

* feat(act): fix linter errors

---------

Co-authored-by: Ferenc Sárai <[email protected]>

src/bee.ts

@@ -10,6 +10,7 @@ import { makeTopic, makeTopicFromString } from './feed/topic'
 import { DEFAULT_FEED_TYPE, FeedType, assertFeedType } from './feed/type'
 import * as bytes from './modules/bytes'
 import * as bzz from './modules/bzz'
+import * as grantee from './modules/grantee'
 import * as chunk from './modules/chunk'
 import * as balance from './modules/debug/balance'
 import * as chequebook from './modules/debug/chequebook'
@@ -81,6 +82,8 @@ import type {
   UploadOptions,
   UploadRedundancyOptions,
   UploadResultWithCid,
+  GranteesResult,
+  GetGranteesResult,
   WalletBalance,
 } from './types'
 import {
@@ -260,7 +263,7 @@ export class Bee {
     data: Uint8Array,
     options?: UploadOptions,
     requestOptions?: BeeRequestOptions,
-  ): Promise<Reference> {
+  ): Promise<UploadResult> {
     assertBatchId(postageBatchId)
 
     if (!(data instanceof Uint8Array)) {
@@ -297,6 +300,68 @@ export class Bee {
     return chunk.download(this.getRequestOptionsForCall(options), reference)
   }
 
+  /**
+   * Create a grantees list from the given array of public keys.
+   *
+   * The grantees list can be obtained with the `getGrantees` method.
+   *
+   * @param postageBatchId - The ID of the postage batch.
+   * @param grantees - An array of public keys representing the grantees.
+   * @param requestOptions - Optional request options.
+   * @returns A promise that resolves to a `GranteesResult` object.
+   */
+  async createGrantees(
+    postageBatchId: string | BatchId,
+    grantees: string[],
+    requestOptions?: BeeRequestOptions,
+  ): Promise<GranteesResult> {
+    assertBatchId(postageBatchId)
+
+    return grantee.createGrantees(this.getRequestOptionsForCall(requestOptions), postageBatchId, grantees)
+  }
+
+  /**
+   * Retrieves the grantees for a given reference.
+   *
+   * @param reference - The reference.
+   * @param requestOptions - Optional request options.
+   * @returns A promise that resolves to a `GetGranteesResult object.
+   */
+  async getGrantees(
+    reference: ReferenceOrEns | string,
+    requestOptions?: BeeRequestOptions,
+  ): Promise<GetGranteesResult> {
+    return grantee.getGrantees(reference, this.getRequestOptionsForCall(requestOptions))
+  }
+
+  /**
+   * Updates the grantees of a specific reference and history.
+   *
+   * @param reference - The reference.
+   * @param history - The history.
+   * @param postageBatchId - The ID of the postage batch.
+   * @param grantees - The grantees.
+   * @param requestOptions - Optional request options.
+   * @returns A Promise that resolves to to a `GranteesResult` object.
+   */
+  async patchGrantees(
+    reference: Reference | string,
+    histrory: Reference | string,
+    postageBatchId: string | BatchId,
+    grantees: string,
+    requestOptions?: BeeRequestOptions,
+  ): Promise<GranteesResult> {
+    assertBatchId(postageBatchId)
+
+    return grantee.patchGrantees(
+      reference,
+      histrory,
+      postageBatchId,
+      grantees,
+      this.getRequestOptionsForCall(requestOptions),
+    )
+  }
+
   /**
    * Upload single file to a Bee node.
    *
@@ -1024,7 +1089,7 @@ export class Bee {
     data: T,
     options?: JsonFeedOptions,
     requestOptions?: BeeRequestOptions,
-  ): Promise<Reference> {
+  ): Promise<UploadResult> {
     assertRequestOptions(options, 'JsonFeedOptions')
     assertBatchId(postageBatchId)
 

src/chunk/soc.ts

@@ -1,7 +1,15 @@
 import { Binary } from 'cafe-utility'
 import * as chunkAPI from '../modules/chunk'
 import * as socAPI from '../modules/soc'
-import { BatchId, BeeRequestOptions, PlainBytesReference, Reference, Signature, Signer, UploadOptions } from '../types'
+import {
+  BatchId,
+  BeeRequestOptions,
+  PlainBytesReference,
+  Signature,
+  Signer,
+  UploadOptions,
+  UploadResult,
+} from '../types'
 import { Bytes, bytesAtOffset, bytesEqual, flexBytesAtOffset } from '../utils/bytes'
 import { BeeError } from '../utils/error'
 import { EthAddress } from '../utils/eth'
@@ -130,7 +138,7 @@ export async function uploadSingleOwnerChunk(
   chunk: SingleOwnerChunk,
   postageBatchId: BatchId,
   options?: UploadOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   const owner = bytesToHex(chunk.owner())
   const identifier = bytesToHex(chunk.identifier())
   const signature = bytesToHex(chunk.signature())
@@ -156,7 +164,7 @@ export async function uploadSingleOwnerChunkData(
   identifier: Identifier,
   data: Uint8Array,
   options?: UploadOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   assertAddress(postageBatchId)
   const cac = makeContentAddressedChunk(data)
   const soc = await makeSingleOwnerChunk(cac, identifier, signer)

src/feed/index.ts

@@ -15,6 +15,7 @@ import {
   Signer,
   Topic,
   UploadOptions,
+  UploadResult,
 } from '../types'
 import { Bytes, bytesAtOffset, makeBytes } from '../utils/bytes'
 import { EthAddress, HexEthAddress, makeHexEthAddress } from '../utils/eth'
@@ -73,7 +74,7 @@ export async function updateFeed(
   reference: BytesReference,
   postageBatchId: BatchId,
   options?: FeedUploadOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   const ownerHex = makeHexEthAddress(signer.address)
   const nextIndex = options?.index ?? (await findNextIndex(requestOptions, ownerHex, topic, options))
 

src/feed/json.ts

@@ -6,8 +6,8 @@ import {
   FeedReader,
   FeedWriter,
   JsonFeedOptions,
-  Reference,
   UploadOptions,
+  UploadResult,
 } from '../types'
 import { isError } from '../utils/type'
 
@@ -38,7 +38,7 @@ export async function setJsonData(
   data: AnyJson,
   options?: JsonFeedOptions & UploadOptions,
   requestOptions?: BeeRequestOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   const serializedData = serializeJson(data)
   const { reference } = await bee.uploadData(postageBatchId, serializedData, options, requestOptions)
 

src/modules/bytes.ts

@@ -44,6 +44,7 @@ export async function upload(
   return {
     reference: response.data.reference,
     tagUid: response.headers['swarm-tag'] ? makeTagUid(response.headers['swarm-tag']) : undefined,
+    history_address: response.headers['swarm-act-history-address'] || '',
   }
 }
 

src/modules/bzz.ts

@@ -78,6 +78,7 @@ export async function uploadFile(
   return {
     reference: response.data.reference,
     tagUid: response.headers['swarm-tag'] ? makeTagUid(response.headers['swarm-tag']) : undefined,
+    history_address: response.headers['swarm-act-history-address'] || '',
   }
 }
 
@@ -180,5 +181,6 @@ export async function uploadCollection(
   return {
     reference: response.data.reference,
     tagUid: response.headers['swarm-tag'] ? makeTagUid(response.headers['swarm-tag']) : undefined,
+    history_address: response.headers['swarm-act-history-address'] || '',
   }
 }

src/modules/chunk.ts

@@ -2,14 +2,15 @@ import type {
   BatchId,
   BeeRequestOptions,
   Data,
-  Reference,
   ReferenceOrEns,
   ReferenceResponse,
   UploadOptions,
+  UploadResult,
 } from '../types'
 import { wrapBytesWithHelpers } from '../utils/bytes'
 import { extractUploadHeaders } from '../utils/headers'
 import { http } from '../utils/http'
+import { makeTagUid } from '../utils/type'
 
 const endpoint = 'chunks'
 
@@ -30,7 +31,7 @@ export async function upload(
   data: Uint8Array,
   postageBatchId: BatchId,
   options?: UploadOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   const response = await http<ReferenceResponse>(requestOptions, {
     method: 'post',
     url: `${endpoint}`,
@@ -42,7 +43,11 @@ export async function upload(
     responseType: 'json',
   })
 
-  return response.data.reference
+  return {
+    reference: response.data.reference,
+    tagUid: response.headers['swarm-tag'] ? makeTagUid(response.headers['swarm-tag']) : undefined,
+    history_address: response.headers['swarm-act-history-address'] || '',
+  }
 }
 
 /**

src/modules/grantee.ts

@@ -0,0 +1,68 @@
+import { BatchId, BeeRequestOptions, GetGranteesResult, GranteesResult } from '../types'
+import { extractRedundantUploadHeaders } from '../utils/headers'
+import { http } from '../utils/http'
+
+const granteeEndpoint = 'grantee'
+
+export async function getGrantees(reference: string, requestOptions: BeeRequestOptions): Promise<GetGranteesResult> {
+  const response = await http<GetGranteesResult>(requestOptions, {
+    method: 'get',
+    url: `${granteeEndpoint}/${reference}`,
+    responseType: 'json',
+  })
+
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    data: response.data.data,
+  }
+}
+
+export async function createGrantees(
+  requestOptions: BeeRequestOptions,
+  postageBatchId: BatchId,
+  grantees: string[],
+): Promise<GranteesResult> {
+  const response = await http<GranteesResult>(requestOptions, {
+    method: 'post',
+    url: granteeEndpoint,
+    data: { grantees: grantees },
+    headers: {
+      ...extractRedundantUploadHeaders(postageBatchId),
+    },
+    responseType: 'json',
+  })
+
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    ref: response.data.ref,
+    historyref: response.data.historyref,
+  }
+}
+
+export async function patchGrantees(
+  reference: string,
+  historyRef: string,
+  postageBatchId: BatchId,
+  grantees: string,
+  requestOptions: BeeRequestOptions,
+): Promise<GranteesResult> {
+  const response = await http<GranteesResult>(requestOptions, {
+    method: 'patch',
+    url: `${granteeEndpoint}/${reference}`,
+    data: grantees,
+    headers: {
+      ...extractRedundantUploadHeaders(postageBatchId),
+      'swarm-act-history-address': historyRef,
+    },
+    responseType: 'json',
+  })
+
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    ref: response.data.ref,
+    historyref: response.data.historyref,
+  }
+}

src/modules/soc.ts

@@ -1,6 +1,7 @@
-import { BatchId, BeeRequestOptions, Reference, ReferenceResponse, UploadOptions } from '../types'
+import { BatchId, BeeRequestOptions, ReferenceResponse, UploadOptions, UploadResult } from '../types'
 import { extractUploadHeaders } from '../utils/headers'
 import { http } from '../utils/http'
+import { makeTagUid } from '../utils/type'
 
 const socEndpoint = 'soc'
 
@@ -23,7 +24,7 @@ export async function upload(
   data: Uint8Array,
   postageBatchId: BatchId,
   options?: UploadOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   const response = await http<ReferenceResponse>(requestOptions, {
     method: 'post',
     url: `${socEndpoint}/${owner}/${identifier}`,
@@ -36,5 +37,9 @@ export async function upload(
     params: { sig: signature },
   })
 
-  return response.data.reference
+  return {
+    reference: response.data.reference,
+    tagUid: response.headers['swarm-tag'] ? makeTagUid(response.headers['swarm-tag']) : undefined,
+    history_address: response.headers['swarm-act-history-address'] || '',
+  }
 }