feat: add function for getting a specific global batch

src/bee.ts

@@ -1153,7 +1153,7 @@
     for (let i = 0n; i < 0xffffn; i++) {
       const signer = new PrivateKey(Binary.numberToUint256(start + i, 'BE'))
       const socAddress = makeSOCAddress(identifier, signer.publicKey().address())
       // TODO: test the significance of the hardcoded 256
       const actualProximity = 256 - Binary.proximity(socAddress.toUint8Array(), targetOverlay.toUint8Array())
 
       if (actualProximity <= 256 - proximity) {
@@ -1843,7 +1843,7 @@
     gasPrice?: NumberString | string | bigint,
     requestOptions?: BeeRequestOptions,
   ): Promise<TransactionId> {
     // TODO: check BZZ in tests
     const amountString =
       amount instanceof BZZ ? amount.toPLURString() : asNumberString(amount, { min: 1n, name: 'amount' })
 
@@ -2522,6 +2522,21 @@
     )
   }
 
+  /**
+   * 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.
    *
@@ -2550,7 +2565,7 @@
    * @deprecated Use `getPostageBatches` instead
    */
   async getAllPostageBatch(requestOptions?: BeeRequestOptions): Promise<PostageBatch[]> {
     return stamps.getAllPostageBatches(this.getRequestOptionsForCall(requestOptions)) // TODO: remove in June 2025
   }
 
   /**
@@ -2561,7 +2576,7 @@
    * @deprecated Use `getGlobalPostageBatches` instead
    */
   async getAllGlobalPostageBatch(requestOptions?: BeeRequestOptions): Promise<GlobalPostageBatch[]> {
     return stamps.getGlobalPostageBatches(this.getRequestOptionsForCall(requestOptions)) // TODO: remove in June 2025
   }
 
   /**

src/modules/debug/stamps.ts

@@ -11,9 +11,11 @@ import {
   BatchIdResponse,
   GetAllPostageBatchesResponse,
   GetGlobalPostageBatchesResponse,
+  GetGlobalPostageBatchResponse,
   GetPostageBatchBucketsResponse,
   GetPostageBatchResponse,
 } from '../../types/schema/stamps'
+
 import { http } from '../../utils/http'
 import { mapPostageBatch } from '../../utils/stamps'
 import { BatchId } from '../../utils/typed-bytes'
@@ -31,6 +33,19 @@ export async function getGlobalPostageBatches(requestOptions: BeeRequestOptions)
   return GetGlobalPostageBatchesResponse.parse(response.data).batches
 }
 
+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/types/schema/stamps.ts

@@ -15,19 +15,19 @@ export const RawPostageBatchSchema = z.object({
   batchTTL: z.number(),
 })
 
+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' })),
+})
+
 export const GetGlobalPostageBatchesResponse = z.object({
-  batches: z.array(
-    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' })),
-    }),
-  ),
+  batches: z.array(GetGlobalPostageBatchResponse),
 })
 
 export const GetAllPostageBatchesResponse = z.object({

test/integration/stamp.spec.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)