feat!: return tags for uploads

package.json

@@ -38,7 +38,7 @@
     "test": "npm run compile:browser && jest --verbose --selectProjects=node:unit node:integration dom:integration --config=jest.config.ts",
     "test:integration:browser": "npm run compile:browser && jest --verbose --selectProjects=dom:integration --config=jest.config.ts",
     "test:integration:node": "jest --verbose --selectProjects=node:integration --config=jest.config.ts",
-    "test:integration": "npm run compile:browser && jest --verbose --selectProjects=node:integration dom:integration --config=jest.config.ts ",
+    "test:integration": "npm run compile:browser && jest --verbose --selectProjects=node:integration dom:integration --config=jest.config.ts",
     "test:unit": "jest --verbose --selectProjects=node:unit --config=jest.config.ts ",
     "test:node": "jest --verbose --selectProjects=node:unit node:integration --config=jest.config.ts",
     "test:browser": "npm run test:integration:browser",

src/bee.ts

@@ -36,15 +36,17 @@ import {
   makeTagUid,
 } from './utils/type'
 import { setJsonData, getJsonData } from './feed/json'
-import { makeCollectionFromFS, makeCollectionFromFileList } from './utils/collection'
+import { makeCollectionFromFS, makeCollectionFromFileList, assertCollection } from './utils/collection'
 import {
   AllTagsOptions,
+  Collection,
   Ky,
   NumberString,
   PostageBatchOptions,
   Readable,
   STAMPS_DEPTH_MAX,
   STAMPS_DEPTH_MIN,
+  UploadResult,
 } from './types'
 
 import type { Options as KyOptions } from 'ky-universal'
@@ -155,7 +157,7 @@ export class Bee {
     postageBatchId: string | BatchId,
     data: string | Uint8Array,
     options?: UploadOptions,
-  ): Promise<Reference> {
+  ): Promise<UploadResult> {
     assertBatchId(postageBatchId)
     assertData(data)
 
@@ -211,7 +213,7 @@ export class Bee {
     data: string | Uint8Array | Readable | File,
     name?: string,
     options?: FileUploadOptions,
-  ): Promise<Reference> {
+  ): Promise<UploadResult> {
     assertBatchId(postageBatchId)
     assertFileData(data)
 
@@ -230,10 +232,10 @@ export class Bee {
       return bzz.uploadFile(this.ky, fileData, postageBatchId, fileName, fileOptions)
     } else if (isReadable(data) && options?.tag && !options.size) {
       // TODO: Needed until https://github.com/ethersphere/bee/issues/2317 is resolved
-      const reference = await bzz.uploadFile(this.ky, data, postageBatchId, name, options)
-      await this.updateTag(options.tag, reference)
+      const result = await bzz.uploadFile(this.ky, data, postageBatchId, name, options)
+      await this.updateTag(options.tag, result.reference)
 
-      return reference
+      return result
     } else {
       return bzz.uploadFile(this.ky, data, postageBatchId, name, options)
     }
@@ -275,6 +277,9 @@ export class Bee {
    *
    * Uses the FileList API from the browser.
    *
+   * The returned `UploadResult.tag` might be undefined if called in CORS-enabled environment.
+   * This will be fixed upon next Bee release. https://github.com/ethersphere/bee-js/issues/406
+   *
    * @param postageBatchId Postage BatchId to be used to upload the data with
    * @param fileList list of files to be uploaded
    * @param options Additional options like tag, encryption, pinning
@@ -287,7 +292,7 @@ export class Bee {
     postageBatchId: string | BatchId,
     fileList: FileList | File[],
     options?: CollectionUploadOptions,
-  ): Promise<Reference> {
+  ): Promise<UploadResult> {
     assertBatchId(postageBatchId)
 
     if (options) assertCollectionUploadOptions(options)
@@ -297,11 +302,37 @@ export class Bee {
     return bzz.uploadCollection(this.ky, data, postageBatchId, options)
   }
 
+  /**
+   * Upload Collection that you can assembly yourself.
+   *
+   * The returned `UploadResult.tag` might be undefined if called in CORS-enabled environment.
+   * This will be fixed upon next Bee release. https://github.com/ethersphere/bee-js/issues/406
+   *
+   * @param postageBatchId
+   * @param collection
+   * @param options
+   */
+  async uploadCollection(
+    postageBatchId: string | BatchId,
+    collection: Collection<Uint8Array | Readable>,
+    options?: CollectionUploadOptions,
+  ): Promise<UploadResult> {
+    assertBatchId(postageBatchId)
+    assertCollection(collection)
+
+    if (options) assertCollectionUploadOptions(options)
+
+    return bzz.uploadCollection(this.ky, collection, postageBatchId, options)
+  }
+
   /**
    * Upload collection of files.
    *
    * Available only in Node.js as it uses the `fs` module.
    *
+   * The returned `UploadResult.tag` might be undefined if called in CORS-enabled environment.
+   * This will be fixed upon next Bee release. https://github.com/ethersphere/bee-js/issues/406
+   *
    * @param postageBatchId Postage BatchId to be used to upload the data with
    * @param dir the path of the files to be uploaded
    * @param options Additional options like tag, encryption, pinning
@@ -314,7 +345,7 @@ export class Bee {
     postageBatchId: string | BatchId,
     dir: string,
     options?: CollectionUploadOptions,
-  ): Promise<Reference> {
+  ): Promise<UploadResult> {
     assertBatchId(postageBatchId)
 
     if (options) assertCollectionUploadOptions(options)

src/feed/json.ts

@@ -26,7 +26,7 @@ export async function setJsonData(
   data: AnyJson,
 ): Promise<Reference> {
   const serializedData = serializeJson(data)
-  const reference = await bee.uploadData(postageBatchId, serializedData)
+  const { reference } = await bee.uploadData(postageBatchId, serializedData)
 
   return writer.upload(postageBatchId, reference)
 }

src/modules/bytes.ts

@@ -3,6 +3,8 @@ import { prepareData } from '../utils/data'
 import { extractUploadHeaders } from '../utils/headers'
 import { http } from '../utils/http'
 import { wrapBytesWithHelpers } from '../utils/bytes'
+import { UploadResult } from '../types'
+import { makeTagUid } from '../utils/type'
 
 const endpoint = 'bytes'
 
@@ -19,7 +21,7 @@ export async function upload(
   data: string | Uint8Array,
   postageBatchId: BatchId,
   options?: UploadOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   const response = await http<{ reference: Reference }>(ky, {
     path: endpoint,
     method: 'post',
@@ -31,7 +33,10 @@ export async function upload(
     },
   })
 
-  return response.data.reference
+  return {
+    reference: response.data.reference,
+    tagUid: makeTagUid(response.headers.get('swarm-tag')),
+  }
 }
 
 /**

src/modules/bzz.ts

@@ -9,6 +9,7 @@ import {
   Readable,
   Reference,
   UploadHeaders,
+  UploadResult,
 } from '../types'
 import { extractUploadHeaders, readFileHeaders } from '../utils/headers'
 import { http } from '../utils/http'
@@ -17,6 +18,7 @@ import { makeTar } from '../utils/tar'
 import { assertCollection } from '../utils/collection'
 import { wrapBytesWithHelpers } from '../utils/bytes'
 import { isReadable } from '../utils/stream'
+import { makeTagUid } from '../utils/type'
 
 const bzzEndpoint = 'bzz'
 
@@ -50,7 +52,7 @@ export async function uploadFile(
   postageBatchId: BatchId,
   name?: string,
   options?: FileUploadOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   if (isReadable(data) && !options?.contentType) {
     if (!options) options = {}
 
@@ -68,7 +70,10 @@ export async function uploadFile(
     responseType: 'json',
   })
 
-  return response.data.reference
+  return {
+    reference: response.data.reference,
+    tagUid: makeTagUid(response.headers.get('swarm-tag')),
+  }
 }
 
 /**
@@ -151,7 +156,7 @@ export async function uploadCollection(
   collection: Collection<Uint8Array>,
   postageBatchId: BatchId,
   options?: CollectionUploadOptions,
-): Promise<Reference> {
+): Promise<UploadResult> {
   assertCollection(collection)
   const tarData = makeTar(collection)
 
@@ -167,5 +172,8 @@ export async function uploadCollection(
     },
   })
 
-  return response.data.reference
+  return {
+    reference: response.data.reference,
+    tagUid: response.headers.get('swarm-tag') ? makeTagUid(response.headers.get('swarm-tag')) : undefined,
+  }
 }

src/types/index.ts

@@ -94,6 +94,26 @@ export interface BeeOptions {
   onResponse?: HookCallback<BeeResponse>
 }
 
+/**
+ * Result of upload calls.
+ */
+export interface UploadResult {
+  /**
+   * Reference of the uploaded data
+   */
+  reference: Reference
+
+  /**
+   * Automatically created tag's UID.
+   *
+   * There is bug in Bee, that does not return correct CORS header (Access-Control-Expose-Headers) for the `Swarm-Tag` to be exposed
+   * in browser when uploading collection. The `tagUid` is marked as optional even though in 99% of results
+   * it is present. The Optional mark will be removed with next Bee release.
+   * TODO: Remove Optional with next Bee release: https://github.com/ethersphere/bee-js/issues/406
+   */
+  tagUid?: number
+}
+
 export interface UploadOptions {
   /**
    * Will pin the data locally in the Bee node as well.

src/utils/type.ts

@@ -275,13 +275,29 @@ export function assertAllTagsOptions(entry: unknown): asserts entry is AllTagsOp
  * Utility functions that return Tag UID
  * @param tagUid
  */
-export function makeTagUid(tagUid: number | Tag): number {
+export function makeTagUid(tagUid: number | Tag | string | null | undefined): number {
+  if (tagUid === undefined || tagUid === null) {
+    throw new TypeError('TagUid was expected but got undefined or null instead!')
+  }
+
   if (isTag(tagUid)) {
     return tagUid.uid
   } else if (typeof tagUid === 'number') {
     assertNonNegativeInteger(tagUid, 'UID')
 
     return tagUid
+  } else if (typeof tagUid === 'string') {
+    const int = parseInt(tagUid)
+
+    if (isNaN(int)) {
+      throw new TypeError('Passed tagUid string is not valid integer!')
+    }
+
+    if (int < 0) {
+      throw new TypeError(`TagUid was expected to be positive non-negative integer! Got ${int}`)
+    }
+
+    return int
   }
 
   throw new TypeError('tagUid has to be either Tag or a number (UID)!')

test/integration/bee-class.browser.spec.ts

@@ -76,7 +76,7 @@ describe('Bee class - in browser', () => {
         const bee = new window.BeeJs.Bee(BEE_URL)
         const files: File[] = [new File(['hello'], 'hello')]
 
-        return await bee.uploadFiles(batchId, files)
+        return (await bee.uploadFiles(batchId, files)).reference
       },
       BEE_URL,
       batchId,
@@ -139,7 +139,7 @@ describe('Bee class - in browser', () => {
             contentType: 'text/plain',
           })
 
-          return reference
+          return reference.reference
         },
         BEE_URL,
         batchId,
@@ -152,7 +152,7 @@ describe('Bee class - in browser', () => {
     })
 
     it('should download file with stream', async () => {
-      const reference = await bzz.uploadFile(beeKy(), 'hello awesome world', batchId)
+      const result = await bzz.uploadFile(beeKy(), 'hello awesome world', batchId)
 
       const content = (await page.evaluate(
         async (BEE_URL, reference) => {
@@ -177,7 +177,7 @@ describe('Bee class - in browser', () => {
           return new TextDecoder().decode(await blob.arrayBuffer())
         },
         BEE_URL,
-        reference,
+        result.reference,
       )) as string
 
       expect(content).toEqual('hello awesome world')