fix: allow fetching stamps with custom effective size calculations (#1105)

* fix: allow fetching stamps with custom effective size calculations

* docs: jsdocs

* test: update test coverage

* test: update test coverage

* refactor: use a method-based approach

* chore: remove dead jsdocs

* test: update test coverage

* test: update test coverage

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: Cafe137

src/bee.ts

@@ -2350,17 +2350,26 @@ export class Bee {
    *
    * @param postageBatchId Batch ID
    * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
+   * @param encryption Assume that uploads with this postage batch are encrypted, which skews the capacity.
+   * @param erasureCodeLevel Assume that uploads with this postage batch are erasure coded, which skews the capacity.
    *
    * @see [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive)
    * @see [Bee Debug API reference - `GET /stamps/${id}`](https://docs.ethswarm.org/api/#tag/Postage-Stamps/paths/~1stamps~1%7Bbatch_id%7D/get)
    */
   async getPostageBatch(
     postageBatchId: BatchId | Uint8Array | string,
     requestOptions?: BeeRequestOptions,
+    encryption?: boolean,
+    erasureCodeLevel?: RedundancyLevel,
   ): Promise<PostageBatch> {
     postageBatchId = new BatchId(postageBatchId)
 
-    return stamps.getPostageBatch(this.getRequestOptionsForCall(requestOptions), postageBatchId)
+    return stamps.getPostageBatch(
+      this.getRequestOptionsForCall(requestOptions),
+      postageBatchId,
+      encryption,
+      erasureCodeLevel,
+    )
   }
 
   /**

src/modules/debug/stamps.ts

@@ -6,6 +6,7 @@ import type {
   PostageBatch,
   PostageBatchBuckets,
   PostageBatchOptions,
+  RedundancyLevel,
 } from '../../types'
 import { Duration } from '../../utils/duration'
 import { http } from '../../utils/http'
@@ -58,6 +59,8 @@ export async function getAllPostageBatches(requestOptions: BeeRequestOptions): P
     const batchTTL = normalizeBatchTTL(Types.asNumber(x.batchTTL, { name: 'batchTTL' }))
     const duration = Duration.fromSeconds(batchTTL)
 
+    const effectiveBytes = getStampEffectiveBytes(depth)
+
     return {
       batchID: new BatchId(Types.asString(x.batchID, { name: 'batchID' })),
       utilization,
@@ -70,17 +73,29 @@ export async function getAllPostageBatches(requestOptions: BeeRequestOptions): P
       immutableFlag: Types.asBoolean(x.immutableFlag, { name: 'immutableFlag' }),
       usage,
       usageText: `${Math.round(usage * 100)}%`,
-      size: Size.fromBytes(getStampEffectiveBytes(depth)),
-      remainingSize: Size.fromBytes(Math.ceil(getStampEffectiveBytes(depth) * (1 - usage))),
+      size: Size.fromBytes(effectiveBytes),
+      remainingSize: Size.fromBytes(Math.ceil(effectiveBytes * (1 - usage))),
       theoreticalSize: Size.fromBytes(getStampTheoreticalBytes(depth)),
       duration,
+      calculateSize(encryption, redundancyLevel) {
+        const effectiveBytes = getStampEffectiveBytes(this.depth, encryption, redundancyLevel)
+
+        return Size.fromBytes(effectiveBytes)
+      },
+      calculateRemainingSize(encryption, redundancyLevel) {
+        const effectiveBytes = getStampEffectiveBytes(this.depth, encryption, redundancyLevel)
+
+        return Size.fromBytes(Math.ceil(effectiveBytes * (1 - this.usage)))
+      },
     }
   })
 }
 
 export async function getPostageBatch(
   requestOptions: BeeRequestOptions,
   postageBatchId: BatchId,
+  encryption?: boolean,
+  erasureCodeLevel?: RedundancyLevel,
 ): Promise<PostageBatch> {
   const response = await http<unknown>(requestOptions, {
     method: 'get',
@@ -97,6 +112,8 @@ export async function getPostageBatch(
   const batchTTL = normalizeBatchTTL(Types.asNumber(body.batchTTL, { name: 'batchTTL' }))
   const duration = Duration.fromSeconds(batchTTL)
 
+  const effectiveBytes = getStampEffectiveBytes(depth, encryption, erasureCodeLevel)
+
   return {
     batchID: new BatchId(Types.asString(body.batchID, { name: 'batchID' })),
     utilization,
@@ -109,10 +126,20 @@ export async function getPostageBatch(
     immutableFlag: Types.asBoolean(body.immutableFlag, { name: 'immutableFlag' }),
     usage,
     usageText: `${Math.round(usage * 100)}%`,
-    size: Size.fromBytes(getStampEffectiveBytes(depth)),
-    remainingSize: Size.fromBytes(Math.ceil(getStampEffectiveBytes(depth) * (1 - usage))),
+    size: Size.fromBytes(effectiveBytes),
+    remainingSize: Size.fromBytes(Math.ceil(effectiveBytes * (1 - usage))),
     theoreticalSize: Size.fromBytes(getStampTheoreticalBytes(depth)),
     duration,
+    calculateSize(encryption, redundancyLevel) {
+      const effectiveBytes = getStampEffectiveBytes(depth, encryption, redundancyLevel)
+
+      return Size.fromBytes(effectiveBytes)
+    },
+    calculateRemainingSize(encryption, redundancyLevel) {
+      const effectiveBytes = getStampEffectiveBytes(depth, encryption, redundancyLevel)
+
+      return Size.fromBytes(Math.ceil(effectiveBytes * (1 - usage)))
+    },
   }
 }
 

src/types/index.ts

@@ -544,6 +544,16 @@ export interface PostageBatch {
    * Theoretical size in bytes
    */
   theoreticalSize: Size
+  /**
+   * Calculates the effective size of data that can be uploaded with this postage batch
+   * based on whether encryption is used and the desired redundancy level.
+   */
+  calculateSize(encryption: boolean, redundancyLevel: RedundancyLevel): Size
+  /**
+   * Calculates the remaining size of data that can be uploaded with this postage batch
+   * based on whether encryption is used and the desired redundancy level.
+   */
+  calculateRemainingSize(encryption: boolean, redundancyLevel: RedundancyLevel): Size
 }
 
 export interface BatchBucket {

test/coverage/coverage-summary.json

@@ -1,4 +1,4 @@
-{"total": {"lines":{"total":2468,"covered":2026,"skipped":0,"pct":82.09},"statements":{"total":2511,"covered":2065,"skipped":0,"pct":82.23},"functions":{"total":597,"covered":478,"skipped":0,"pct":80.06},"branches":{"total":563,"covered":356,"skipped":0,"pct":63.23},"branchesTrue":{"total":0,"covered":0,"skipped":0,"pct":100}}
+{"total": {"lines":{"total":2478,"covered":2028,"skipped":0,"pct":81.84},"statements":{"total":2521,"covered":2067,"skipped":0,"pct":81.99},"functions":{"total":601,"covered":478,"skipped":0,"pct":79.53},"branches":{"total":563,"covered":356,"skipped":0,"pct":63.23},"branchesTrue":{"total":0,"covered":0,"skipped":0,"pct":100}}
 ,"/home/runner/work/bee-js/bee-js/src/bee-dev.ts": {"lines":{"total":14,"covered":5,"skipped":0,"pct":35.71},"functions":{"total":2,"covered":0,"skipped":0,"pct":0},"statements":{"total":14,"covered":5,"skipped":0,"pct":35.71},"branches":{"total":0,"covered":0,"skipped":0,"pct":100}}
 ,"/home/runner/work/bee-js/bee-js/src/bee.ts": {"lines":{"total":445,"covered":370,"skipped":0,"pct":83.14},"functions":{"total":127,"covered":104,"skipped":0,"pct":81.88},"statements":{"total":448,"covered":373,"skipped":0,"pct":83.25},"branches":{"total":115,"covered":67,"skipped":0,"pct":58.26}}
 ,"/home/runner/work/bee-js/bee-js/src/index.ts": {"lines":{"total":16,"covered":16,"skipped":0,"pct":100},"functions":{"total":10,"covered":7,"skipped":0,"pct":70},"statements":{"total":25,"covered":25,"skipped":0,"pct":100},"branches":{"total":0,"covered":0,"skipped":0,"pct":100}}
@@ -28,7 +28,7 @@
 ,"/home/runner/work/bee-js/bee-js/src/modules/debug/connectivity.ts": {"lines":{"total":35,"covered":28,"skipped":0,"pct":80},"functions":{"total":11,"covered":7,"skipped":0,"pct":63.63},"statements":{"total":36,"covered":29,"skipped":0,"pct":80.55},"branches":{"total":2,"covered":2,"skipped":0,"pct":100}}
 ,"/home/runner/work/bee-js/bee-js/src/modules/debug/settlements.ts": {"lines":{"total":18,"covered":18,"skipped":0,"pct":100},"functions":{"total":4,"covered":4,"skipped":0,"pct":100},"statements":{"total":18,"covered":18,"skipped":0,"pct":100},"branches":{"total":0,"covered":0,"skipped":0,"pct":100}}
 ,"/home/runner/work/bee-js/bee-js/src/modules/debug/stake.ts": {"lines":{"total":32,"covered":21,"skipped":0,"pct":65.62},"functions":{"total":6,"covered":3,"skipped":0,"pct":50},"statements":{"total":32,"covered":21,"skipped":0,"pct":65.62},"branches":{"total":0,"covered":0,"skipped":0,"pct":100}}
-,"/home/runner/work/bee-js/bee-js/src/modules/debug/stamps.ts": {"lines":{"total":60,"covered":58,"skipped":0,"pct":96.66},"functions":{"total":13,"covered":13,"skipped":0,"pct":100},"statements":{"total":63,"covered":61,"skipped":0,"pct":96.82},"branches":{"total":2,"covered":0,"skipped":0,"pct":0}}
+,"/home/runner/work/bee-js/bee-js/src/modules/debug/stamps.ts": {"lines":{"total":70,"covered":60,"skipped":0,"pct":85.71},"functions":{"total":17,"covered":13,"skipped":0,"pct":76.47},"statements":{"total":73,"covered":63,"skipped":0,"pct":86.3},"branches":{"total":2,"covered":0,"skipped":0,"pct":0}}
 ,"/home/runner/work/bee-js/bee-js/src/modules/debug/states.ts": {"lines":{"total":29,"covered":24,"skipped":0,"pct":82.75},"functions":{"total":5,"covered":4,"skipped":0,"pct":80},"statements":{"total":29,"covered":24,"skipped":0,"pct":82.75},"branches":{"total":0,"covered":0,"skipped":0,"pct":100}}
 ,"/home/runner/work/bee-js/bee-js/src/modules/debug/status.ts": {"lines":{"total":36,"covered":34,"skipped":0,"pct":94.44},"functions":{"total":7,"covered":6,"skipped":0,"pct":85.71},"statements":{"total":36,"covered":34,"skipped":0,"pct":94.44},"branches":{"total":0,"covered":0,"skipped":0,"pct":100}}
 ,"/home/runner/work/bee-js/bee-js/src/modules/debug/transactions.ts": {"lines":{"total":27,"covered":18,"skipped":0,"pct":66.66},"functions":{"total":5,"covered":3,"skipped":0,"pct":60},"statements":{"total":27,"covered":18,"skipped":0,"pct":66.66},"branches":{"total":1,"covered":0,"skipped":0,"pct":0}}