Merge pull request #6113 from BitGo/BTC-2110-invoice-payment-pagination

feat: added pagination in invoice

Author: parvbitgo067

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

@@ -58,7 +58,7 @@ async function main(): Promise<void> {
       status,
       limit: limit ? BigInt(limit) : undefined,
     };
-    const invoices = await lightning.listInvoices(query);
+    const { invoices } = await lightning.listInvoices(query);
 
     // Display invoice summary
     console.log(`\nFound ${invoices.length} invoices:`);

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/invoice.ts

@@ -82,10 +82,29 @@ export const InvoiceInfo = t.intersection(
 );
 export type InvoiceInfo = t.TypeOf<typeof InvoiceInfo>;
 
+export const ListInvoicesResponse = t.intersection(
+  [
+    t.type({
+      invoices: t.array(InvoiceInfo),
+    }),
+    t.partial({
+      /**
+       * This is the paymentHash of the last Invoice in the last iteration.
+       * Providing this value as the prevId in the next request will return the next batch of invoices.
+       * */
+      nextBatchPrevId: t.string,
+    }),
+  ],
+  'ListInvoicesResponse'
+);
+export type ListInvoicesResponse = t.TypeOf<typeof ListInvoicesResponse>;
+
 export const InvoiceQuery = t.partial(
   {
     status: InvoiceStatus,
     limit: BigIntFromString,
+    /** paymentHash provided by nextBatchPrevId in the previous list */
+    prevId: t.string,
     startDate: DateFromISOString,
     endDate: DateFromISOString,
   },

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

@@ -26,6 +26,8 @@ import {
   PaymentQuery,
   LightningOnchainWithdrawParams,
   LightningOnchainWithdrawResponse,
+  ListInvoicesResponse,
+  ListPaymentsResponse,
 } from '../codecs';
 import { LightningPaymentIntent, LightningPaymentRequest } from '@bitgo/public-types';
 
@@ -143,9 +145,10 @@ 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
-   * @returns {Promise<InvoiceInfo[]>} List of invoices
+   * @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<InvoiceInfo[]>;
+  listInvoices(params: InvoiceQuery): Promise<ListInvoicesResponse>;
 
   /**
    * Pay a lightning invoice
@@ -181,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
@@ -234,8 +238,8 @@ export class LightningWallet implements ILightningWallet {
     });
   }
 
-  async listInvoices(params: InvoiceQuery): Promise<InvoiceInfo[]> {
-    const returnCodec = t.array(InvoiceInfo);
+  async listInvoices(params: InvoiceQuery): Promise<ListInvoicesResponse> {
+    const returnCodec = ListInvoicesResponse;
     const createInvoiceResponse = await this.wallet.bitgo
       .get(this.wallet.bitgo.url(`/wallet/${this.wallet.id()}/lightning/invoice`, 2))
       .query(InvoiceQuery.encode(params))
@@ -364,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';
@@ -264,17 +266,56 @@ describe('Lightning wallets', function () {
       const listInvoicesNock = nock(bgUrl)
         .get(`/api/v2/wallet/${wallet.wallet.id()}/lightning/invoice`)
         .query(InvoiceQuery.encode(query))
-        .reply(200, [InvoiceInfo.encode(invoice)]);
+        .reply(200, { invoices: [InvoiceInfo.encode(invoice)] });
       const invoiceResponse = await wallet.listInvoices(query);
-      assert.strictEqual(invoiceResponse.length, 1);
-      assert.deepStrictEqual(invoiceResponse[0], invoice);
+      assert.strictEqual(invoiceResponse.invoices.length, 1);
+      assert.deepStrictEqual(invoiceResponse.invoices[0], invoice);
+      listInvoicesNock.done();
+    });
+
+    it('should work properly with pagination while listing invoices', async function () {
+      const invoice1: InvoiceInfo = {
+        valueMsat: 1000n,
+        paymentHash: 'foo1',
+        invoice: 'tlnfoobar1',
+        walletId: wallet.wallet.id(),
+        status: 'open',
+        expiresAt: new Date(),
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      const invoice2: InvoiceInfo = {
+        ...invoice1,
+        paymentHash: 'foo2',
+        invoice: 'tlnfoobar2',
+      };
+      const invoice3: InvoiceInfo = {
+        ...invoice1,
+        paymentHash: 'foo3',
+        invoice: 'tlnfoobar3',
+      };
+      const allInvoices = [InvoiceInfo.encode(invoice1), InvoiceInfo.encode(invoice2), InvoiceInfo.encode(invoice3)];
+      const query = {
+        status: 'open',
+        startDate: new Date(),
+        limit: 2n,
+      } as InvoiceQuery;
+      const listInvoicesNock = nock(bgUrl)
+        .get(`/api/v2/wallet/${wallet.wallet.id()}/lightning/invoice`)
+        .query(InvoiceQuery.encode(query))
+        .reply(200, { invoices: allInvoices.slice(0, 2), nextBatchPrevId: invoice2.paymentHash });
+      const invoiceResponse = await wallet.listInvoices(query);
+      assert.strictEqual(invoiceResponse.invoices.length, 2);
+      assert.deepStrictEqual(invoiceResponse.invoices[0], invoice1);
+      assert.deepStrictEqual(invoiceResponse.invoices[1], invoice2);
+      assert.strictEqual(invoiceResponse.nextBatchPrevId, invoice2.paymentHash);
       listInvoicesNock.done();
     });
 
     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();
     });
@@ -464,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',