feat: add head bytes endpoint (#941)

* feat: add head bytes endpoint

* test: add integration test for head bytes

src/bee.ts

@@ -71,6 +71,7 @@ import type {
   PublicKey,
   RedistributionState,
   Reference,
+  ReferenceInformation,
   RemovePeerResponse,
   ReserveState,
   SOCReader,
@@ -214,6 +215,18 @@ export class Bee {
     return bytes.upload(this.getRequestOptionsForCall(requestOptions), data, postageBatchId, options)
   }
 
+  /**
+   * Requests content length for a `/bytes` reference
+   *
+   * @see [Bee API reference - `HEAD /bytes/`](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes~1%7Breference%7D/head)
+   */
+  async probeData(reference: ReferenceOrEns | string, options?: BeeRequestOptions): Promise<ReferenceInformation> {
+    assertRequestOptions(options)
+    assertReferenceOrEns(reference)
+
+    return bytes.head(this.getRequestOptionsForCall(options), reference)
+  }
+
   /**
    * Download data as a byte array
    *

src/modules/bytes.ts

@@ -4,6 +4,7 @@ import type {
   Data,
   DownloadRedundancyOptions,
   Reference,
+  ReferenceInformation,
   ReferenceOrEns,
   UploadOptions,
   UploadRedundancyOptions,
@@ -48,6 +49,24 @@ export async function upload(
   }
 }
 
+/**
+ * Requests content length for a reference
+ *
+ * @param requestOptions Options for making requests
+ * @param hash Bee content reference
+ */
+export async function head(requestOptions: BeeRequestOptions, hash: ReferenceOrEns): Promise<ReferenceInformation> {
+  const response = await http<void>(requestOptions, {
+    url: `${endpoint}/${hash}`,
+    method: 'head',
+    responseType: 'json',
+  })
+
+  return {
+    contentLength: parseInt(response.headers['content-length'] as string),
+  }
+}
+
 /**
  * Download data as a byte array
  *

src/types/index.ts

@@ -346,6 +346,10 @@ export interface Pin {
   reference: string
 }
 
+export interface ReferenceInformation {
+  contentLength: number
+}
+
 /**
  * Helper interface that adds utility functions
  * to work more conveniently with bytes in normal

test/integration/bee-class.spec.ts

@@ -624,6 +624,14 @@ describe('Bee class', () => {
     })
   })
 
+  describe('HEAD /bytes', () => {
+    it('should retrieve content length', async function () {
+      const uploadResult = await bee.uploadData(getPostageBatch(), '12345678')
+      const { contentLength } = await bee.probeData(uploadResult.reference)
+      expect(contentLength).toBe(8)
+    })
+  })
+
   describe('JsonFeed', () => {
     it('should set JSON to feed', async function () {
       const TOPIC = 'some=very%nice#topic'