feat: add function for getting a specific global batch

Author: Gergely Békési

package-lock.json

@@ -69,7 +69,8 @@
     "debug": "^4.4.1",
     "isomorphic-ws": "^4.0.1",
     "semver": "^7.3.5",
-    "ws": "^8.20.1"
+    "ws": "^8.20.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@babel/cli": "^7.19.3",

package.json

@@ -2076,9 +2076,9 @@ export class Bee {
    * to buying storage for a certain size and duration on the Swarm network.
    *
    * Use {@link getStorageCost} to calculate the cost of creating a postage batch.
-   * 
+   *
    * For the low level API, use {@link createPostageBatch}.
-   * 
+   *
    * @example const batchId = await bee.buyStorage(Size.fromGigabytes(8), Duration.fromDays(31))
 
    * @param size
@@ -2492,6 +2492,21 @@ export class Bee {
     )
   }
 
+  /**
+   * Returns details for specific globally available postage batch.
+   *
+   * @param postageBatchId Batch ID
+   * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   */
+  async getGlobalPostageBatch(
+    postageBatchId: BatchId | Uint8Array | string,
+    requestOptions?: BeeRequestOptions,
+  ): Promise<GlobalPostageBatch> {
+    postageBatchId = new BatchId(postageBatchId)
+
+    return stamps.getGlobalPostageBatch(this.getRequestOptionsForCall(requestOptions), postageBatchId)
+  }
+
   /**
    * Return detailed information related to buckets for specific postage batch.
    *

src/bee.ts

@@ -8,6 +8,7 @@ import type {
   PostageBatchOptions,
   RedundancyLevel,
 } from '../../types'
+import { GetGlobalPostageBatchResponse } from '../../types/schema'
 import { http } from '../../utils/http'
 import { mapPostageBatch, RawPostageBatch } from '../../utils/stamps'
 import { asNumberString } from '../../utils/type'
@@ -38,6 +39,19 @@ export async function getGlobalPostageBatches(requestOptions: BeeRequestOptions)
   }))
 }
 
+export async function getGlobalPostageBatch(
+  requestOptions: BeeRequestOptions,
+  postageBatchId: BatchId,
+): Promise<GlobalPostageBatch> {
+  const response = await http<unknown>(requestOptions, {
+    method: 'get',
+    url: `${BATCHES_ENDPOINT}/${postageBatchId}`,
+    responseType: 'json',
+  })
+
+  return GetGlobalPostageBatchResponse.parse(response.data)
+}
+
 export async function getAllPostageBatches(requestOptions: BeeRequestOptions): Promise<PostageBatch[]> {
   const response = await http<unknown>(requestOptions, {
     method: 'get',

src/modules/debug/stamps.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod'
+import { asNumberString } from '../utils/type'
+import { BatchId, EthAddress } from '../utils/typed-bytes'
+
+export const GetGlobalPostageBatchResponse = z.object({
+  batchID: z.string().transform(s => new BatchId(s)),
+  batchTTL: z.number(),
+  bucketDepth: z.number(),
+  depth: z.number(),
+  immutable: z.boolean(),
+  owner: z.string().transform(s => new EthAddress(s)),
+  start: z.number(),
+  value: z.string().transform(s => asNumberString(s, { name: 'value' })),
+})

src/types/schema.ts

@@ -20,6 +20,14 @@ test('GET batches', async () => {
   expect(batches.length).toBeGreaterThan(0)
 })
 
+test('GET batch', async () => {
+  const batches = await bee.getGlobalPostageBatches()
+  expect(batches.length).toBeGreaterThan(0)
+
+  const batch = await bee.getGlobalPostageBatch(batches[0].batchID)
+  expect(Objects.deepEquals(batch, batches[0])).toBeTruthy()
+})
+
 test('POST stamps', async () => {
   const response = await bee.createPostageBatch('1098006401', 17, { waitForUsable: true })
   expect(response.toHex()).toHaveLength(64)