feat(sdk): expose document count/sum/average aggregates in js-evo-sdk facade

packages/js-evo-sdk/README.md

@@ -67,7 +67,7 @@ The SDK organises its API into domain-specific facades, each accessible as a pro
 |--------|-------------|
 | [`sdk.addresses`](src/addresses/facade.ts) | Query balances, transfer credits, withdraw to L1 |
 | [`sdk.identities`](src/identities/facade.ts) | Fetch, create, update, and top up identities |
-| [`sdk.documents`](src/documents/facade.ts) | Query, create, replace, delete, and transfer documents |
+| [`sdk.documents`](src/documents/facade.ts) | Query, create, replace, delete, and transfer documents; aggregate `count` / `sum` / `average` over indexed fields |
 | [`sdk.contracts`](src/contracts/facade.ts) | Fetch, publish, and update data contracts |
 | [`sdk.tokens`](src/tokens/facade.ts) | Mint, burn, transfer, freeze tokens and query balances |
 | [`sdk.dpns`](src/dpns/facade.ts) | Register and resolve Dash Platform names |

packages/js-evo-sdk/src/documents/facade.ts

@@ -67,4 +67,48 @@ export class DocumentsFacade {
     const w = await this.sdk.getWasmSdkConnected();
     return w.documentSetPrice(options);
   }
+
+  async count(query: wasm.DocumentsQuery): Promise<Map<string, bigint>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getDocumentsCount(query);
+  }
+
+  async countWithProof(
+    query: wasm.DocumentsQuery,
+  ): Promise<wasm.ProofMetadataResponseTyped<Map<string, bigint>>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getDocumentsCountWithProofInfo(query);
+  }
+
+  async sum(
+    query: wasm.DocumentsQuery,
+    sumProperty: string,
+  ): Promise<Map<string, bigint>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getDocumentsSum(query, sumProperty);
+  }
+
+  async sumWithProof(
+    query: wasm.DocumentsQuery,
+    sumProperty: string,
+  ): Promise<wasm.ProofMetadataResponseTyped<Map<string, bigint>>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getDocumentsSumWithProofInfo(query, sumProperty);
+  }
+
+  async average(
+    query: wasm.DocumentsQuery,
+    averageProperty: string,
+  ): Promise<Map<string, { count: bigint; sum: bigint }>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getDocumentsAverage(query, averageProperty);
+  }
+
+  async averageWithProof(
+    query: wasm.DocumentsQuery,
+    averageProperty: string,
+  ): Promise<wasm.ProofMetadataResponseTyped<Map<string, { count: bigint; sum: bigint }>>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getDocumentsAverageWithProofInfo(query, averageProperty);
+  }
 }

packages/js-evo-sdk/tests/unit/facades/documents.spec.ts

@@ -27,6 +27,12 @@ describe('DocumentsFacade', () => {
   let documentTransferStub: SinonStub;
   let documentPurchaseStub: SinonStub;
   let documentSetPriceStub: SinonStub;
+  let getDocumentsCountStub: SinonStub;
+  let getDocumentsCountWithProofInfoStub: SinonStub;
+  let getDocumentsSumStub: SinonStub;
+  let getDocumentsSumWithProofInfoStub: SinonStub;
+  let getDocumentsAverageStub: SinonStub;
+  let getDocumentsAverageWithProofInfoStub: SinonStub;
 
   beforeEach(async function setup() {
     await init();
@@ -60,6 +66,26 @@ describe('DocumentsFacade', () => {
     documentTransferStub = this.sinon.stub(wasmSdk, 'documentTransfer').resolves();
     documentPurchaseStub = this.sinon.stub(wasmSdk, 'documentPurchase').resolves();
     documentSetPriceStub = this.sinon.stub(wasmSdk, 'documentSetPrice').resolves();
+
+    // Stub aggregate query methods
+    getDocumentsCountStub = this.sinon.stub(wasmSdk, 'getDocumentsCount').resolves(new Map());
+    getDocumentsCountWithProofInfoStub = this.sinon.stub(wasmSdk, 'getDocumentsCountWithProofInfo').resolves({
+      data: new Map(),
+      proof: {},
+      metadata: {},
+    });
+    getDocumentsSumStub = this.sinon.stub(wasmSdk, 'getDocumentsSum').resolves(new Map());
+    getDocumentsSumWithProofInfoStub = this.sinon.stub(wasmSdk, 'getDocumentsSumWithProofInfo').resolves({
+      data: new Map(),
+      proof: {},
+      metadata: {},
+    });
+    getDocumentsAverageStub = this.sinon.stub(wasmSdk, 'getDocumentsAverage').resolves(new Map());
+    getDocumentsAverageWithProofInfoStub = this.sinon.stub(wasmSdk, 'getDocumentsAverageWithProofInfo').resolves({
+      data: new Map(),
+      proof: {},
+      metadata: {},
+    });
   });
 
   describe('query()', () => {
@@ -231,4 +257,91 @@ describe('DocumentsFacade', () => {
       expect(documentSetPriceStub).to.be.calledOnceWithExactly(options);
     });
   });
+
+  describe('count()', () => {
+    it('should count documents matching a query', async () => {
+      const query = {
+        dataContractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
+        documentTypeName: 'grade',
+      };
+
+      await client.documents.count(query);
+
+      expect(getDocumentsCountStub).to.be.calledOnceWithExactly(query);
+    });
+  });
+
+  describe('countWithProof()', () => {
+    it('should count documents and return proof metadata', async () => {
+      const query = {
+        dataContractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
+        documentTypeName: 'grade',
+        where: [['class', '==', 'CS101']],
+      };
+
+      await client.documents.countWithProof(query);
+
+      expect(getDocumentsCountWithProofInfoStub).to.be.calledOnceWithExactly(query);
+    });
+  });
+
+  describe('sum()', () => {
+    it('should aggregate a summable property across matching documents', async () => {
+      const query = {
+        dataContractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
+        documentTypeName: 'grade',
+        where: [['semester', '==', 20251]],
+      };
+      const sumProperty = 'score';
+
+      await client.documents.sum(query, sumProperty);
+
+      expect(getDocumentsSumStub).to.be.calledOnceWithExactly(query, sumProperty);
+    });
+  });
+
+  describe('sumWithProof()', () => {
+    it('should aggregate a summable property with proof metadata', async () => {
+      const query = {
+        dataContractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
+        documentTypeName: 'grade',
+      };
+      const sumProperty = 'score';
+
+      await client.documents.sumWithProof(query, sumProperty);
+
+      expect(getDocumentsSumWithProofInfoStub).to.be.calledOnceWithExactly(query, sumProperty);
+    });
+  });
+
+  describe('average()', () => {
+    it('should return the (count, sum) pair for a summable property', async () => {
+      const query = {
+        dataContractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
+        documentTypeName: 'grade',
+        groupBy: ['class'],
+      };
+      const averageProperty = 'score';
+
+      await client.documents.average(query, averageProperty);
+
+      expect(getDocumentsAverageStub).to.be.calledOnceWithExactly(query, averageProperty);
+    });
+  });
+
+  describe('averageWithProof()', () => {
+    it('should return the (count, sum) pair with proof metadata', async () => {
+      const query = {
+        dataContractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
+        documentTypeName: 'grade',
+        where: [['class', '==', 'CS101']],
+        groupBy: ['semester'],
+      };
+      const averageProperty = 'score';
+
+      await client.documents.averageWithProof(query, averageProperty);
+
+      expect(getDocumentsAverageWithProofInfoStub).to.be.calledOnceWithExactly(query, averageProperty);
+    });
+  });
 });