feat: added pagination in payments

Change response type + test cases

TICKET: BTC-2110

Author: parvbitgo067

examples/ts/btc/lightning/list-payments.ts

@@ -54,7 +54,7 @@ async function main(): Promise<void> {
     }
 
     // List payments with the provided filters
-    const payments = await lightning.listPayments(queryParams);
+    const { payments } = await lightning.listPayments(queryParams);
 
     // Display payment summary
     console.log(`\nFound ${payments.length} payments:`);

modules/abstract-lightning/src/codecs/api/payment.ts

@@ -74,6 +74,23 @@ export const PaymentInfo = t.intersection(
 
 export type PaymentInfo = t.TypeOf<typeof PaymentInfo>;
 
+export const ListPaymentsResponse = t.intersection(
+  [
+    t.type({
+      payments: t.array(PaymentInfo),
+    }),
+    t.partial({
+      /**
+       * This is the paymentHash of the last Payment in the last iteration.
+       * Providing this value as the prevId in the next request will return the next batch of payments.
+       * */
+      nextBatchPrevId: t.string,
+    }),
+  ],
+  'ListPaymentsResponse'
+);
+export type ListPaymentsResponse = t.TypeOf<typeof ListPaymentsResponse>;
+
 /**
  * Payment query parameters
  */
@@ -83,6 +100,8 @@ export const PaymentQuery = t.partial(
     limit: BigIntFromString,
     startDate: DateFromISOString,
     endDate: DateFromISOString,
+    /** paymentHash provided by nextBatchPrevId in the previous list */
+    prevId: t.string,
   },
   'PaymentQuery'
 );

modules/abstract-lightning/src/wallet/lightning.ts

@@ -27,6 +27,7 @@ import {
   LightningOnchainWithdrawParams,
   LightningOnchainWithdrawResponse,
   ListInvoicesResponse,
+  ListPaymentsResponse,
 } from '../codecs';
 import { LightningPaymentIntent, LightningPaymentRequest } from '@bitgo/public-types';
 
@@ -144,7 +145,7 @@ export interface ILightningWallet {
    * @param {bigint} [params.limit] The maximum number of invoices to return
    * @param {Date} [params.startDate] The start date for the query
    * @param {Date} [params.endDate] The end date for the query
-   * @param {Date} [params.prevId] Continue iterating (provided by nextBatchPrevId in the previous list)
+   * @param {string} [params.prevId] Continue iterating (provided by nextBatchPrevId in the previous list)
    * @returns {Promise<ListInvoicesResponse>} List of invoices and nextBatchPrevId
    */
   listInvoices(params: InvoiceQuery): Promise<ListInvoicesResponse>;
@@ -183,9 +184,10 @@ export interface ILightningWallet {
    * @param {bigint} [params.limit] The maximum number of payments to return
    * @param {Date} [params.startDate] The start date for the query
    * @param {Date} [params.endDate] The end date for the query
-   * @returns {Promise<PaymentInfo[]>} List of payments
+   * @param {string} [params.prevId] Continue iterating (provided by nextBatchPrevId in the previous list)
+   * @returns {Promise<ListPaymentsResponse>} List of payments and nextBatchPrevId
    */
-  listPayments(params: PaymentQuery): Promise<PaymentInfo[]>;
+  listPayments(params: PaymentQuery): Promise<ListPaymentsResponse>;
   /**
    * Get transaction details by ID
    * @param {string} txId - Transaction ID to lookup
@@ -366,12 +368,12 @@ export class LightningWallet implements ILightningWallet {
     });
   }
 
-  async listPayments(params: PaymentQuery): Promise<PaymentInfo[]> {
+  async listPayments(params: PaymentQuery): Promise<ListPaymentsResponse> {
     const response = await this.wallet.bitgo
       .get(this.wallet.bitgo.url(`/wallet/${this.wallet.id()}/lightning/payment`, 2))
       .query(PaymentQuery.encode(params))
       .result();
-    return decodeOrElse(t.array(PaymentInfo).name, t.array(PaymentInfo), response, (error) => {
+    return decodeOrElse(ListPaymentsResponse.name, ListPaymentsResponse, response, (error) => {
       throw new Error(`Invalid payment list response: ${error}`);
     });
   }

modules/bitgo/test/v2/unit/lightning/lightningWallets.ts

@@ -16,6 +16,8 @@ import {
   getLightningAuthKeychains,
   updateWalletCoinSpecific,
   LightningOnchainWithdrawParams,
+  PaymentInfo,
+  PaymentQuery,
 } from '@bitgo/abstract-lightning';
 
 import { BitGo, common, GenerateLightningWalletOptions, Wallet, Wallets } from '../../../../src';
@@ -313,7 +315,7 @@ describe('Lightning wallets', function () {
     it('listInvoices should throw error if wp response is invalid', async function () {
       const listInvoicesNock = nock(bgUrl)
         .get(`/api/v2/wallet/${wallet.wallet.id()}/lightning/invoice`)
-        .reply(200, [{ valueMsat: '1000' }]);
+        .reply(200, { invoices: [{ valueMsat: '1000' }] });
       await assert.rejects(async () => await wallet.listInvoices({}), /Invalid list invoices response/);
       listInvoicesNock.done();
     });
@@ -503,6 +505,99 @@ describe('Lightning wallets', function () {
     });
   });
 
+  describe('payments', function () {
+    let wallet: LightningWallet;
+    beforeEach(function () {
+      wallet = getLightningWallet(
+        new Wallet(bitgo, basecoin, {
+          id: 'walletId',
+          coin: 'tlnbtc',
+          subType: 'lightningCustody',
+          coinSpecific: { keys: ['def', 'ghi'] },
+        })
+      ) as LightningWallet;
+    });
+
+    it('should get payments', async function () {
+      const payment: PaymentInfo = {
+        paymentHash: 'foo',
+        walletId: wallet.wallet.id(),
+        txRequestId: 'txReqId',
+        status: 'settled',
+        invoice: 'tlnfoobar',
+        destination: 'destination',
+        feeLimitMsat: 100n,
+        amountMsat: 1000n,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      const query = {
+        status: 'settled',
+        startDate: new Date(),
+        limit: 100n,
+      } as PaymentQuery;
+      const listPaymentsNock = nock(bgUrl)
+        .get(`/api/v2/wallet/${wallet.wallet.id()}/lightning/payment`)
+        .query(PaymentQuery.encode(query))
+        .reply(200, { payments: [PaymentInfo.encode(payment)] });
+      const listPaymentsResponse = await wallet.listPayments(query);
+      assert.strictEqual(listPaymentsResponse.payments.length, 1);
+      assert.deepStrictEqual(listPaymentsResponse.payments[0], payment);
+      listPaymentsNock.done();
+    });
+
+    it('should work properly with pagination while listing payments', async function () {
+      const payment1: PaymentInfo = {
+        paymentHash: 'foo1',
+        walletId: wallet.wallet.id(),
+        txRequestId: 'txReqId1',
+        status: 'settled',
+        invoice: 'tlnfoobar1',
+        destination: 'destination',
+        feeLimitMsat: 100n,
+        amountMsat: 1000n,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      const payment2: PaymentInfo = {
+        ...payment1,
+        paymentHash: 'foo2',
+        txRequestId: 'txReqId2',
+        invoice: 'tlnfoobar2',
+      };
+      const payment3: PaymentInfo = {
+        ...payment1,
+        paymentHash: 'foo3',
+        txRequestId: 'txReqId3',
+        invoice: 'tlnfoobar3',
+      };
+      const allPayments = [PaymentInfo.encode(payment1), PaymentInfo.encode(payment2), PaymentInfo.encode(payment3)];
+      const query = {
+        status: 'settled',
+        startDate: new Date(),
+        limit: 2n,
+      } as PaymentQuery;
+      const listPaymentsNock = nock(bgUrl)
+        .get(`/api/v2/wallet/${wallet.wallet.id()}/lightning/payment`)
+        .query(PaymentQuery.encode(query))
+        .reply(200, { payments: allPayments.slice(0, 2), nextBatchPrevId: payment2.paymentHash });
+      const listPaymentsResponse = await wallet.listPayments(query);
+      assert.strictEqual(listPaymentsResponse.payments.length, 2);
+      assert.deepStrictEqual(listPaymentsResponse.payments[0], payment1);
+      assert.deepStrictEqual(listPaymentsResponse.payments[1], payment2);
+      assert.strictEqual(listPaymentsResponse.nextBatchPrevId, payment2.paymentHash);
+      listPaymentsNock.done();
+    });
+
+    it('listPayments should throw error if wp response is invalid', async function () {
+      const listPaymentsNock = nock(bgUrl)
+        .get(`/api/v2/wallet/${wallet.wallet.id()}/lightning/payment`)
+        .reply(200, { payments: [{ amountMsat: '1000' }] });
+      await assert.rejects(async () => await wallet.listPayments({}), /Invalid payment list response/);
+      listPaymentsNock.done();
+    });
+  });
+
   describe('Get lightning key(s)', function () {
     const walletData = {
       id: 'fakeid',