feat(gl-sdk): add list_invoices, list_pays, and unified list_payments API

Three new Node methods for querying payment history:

- list_invoices(): wraps CLN ListInvoices with full native filtering
  (label, invstring, payment_hash, offer_id) and pagination (index,
  start, limit)
- list_pays(): wraps CLN ListPays with native filtering (bolt11,
  payment_hash, status) and pagination
- list_payments(): merges both into a unified Payment timeline sorted
  newest-first, defaults to COMPLETE status filter

New types: Invoice, InvoiceStatus, Pay, ListInvoicesResponse,
ListPaysResponse, Payment, PaymentDirection, PaymentStatus,
ListPaymentsResponse, ListIndex. Payment includes optional invoice/pay
fields for drill-down access to full CLN-specific details.

Kotlin extensions provide default null parameters for idiomatic API.
Includes Python integration tests and Android instrumented tests.

Author: angelix

docs/superpowers/plans/2026-04-01-list-payments-api.md

@@ -0,0 +1,109 @@
+// Instrumented tests for list_invoices, list_pays, and list_payments.
+// Tests type construction, empty lists on fresh nodes, invoice creation
+// visibility, and status filtering.
+
+package com.blockstream.glsdk
+
+import android.system.Os
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import kotlin.uuid.ExperimentalUuidApi
+import kotlin.uuid.Uuid
+
+@RunWith(AndroidJUnit4::class)
+class ListPaymentTest {
+
+    @Before
+    fun setup() {
+        Os.setenv("RUST_LOG", "trace", true)
+    }
+
+    // BIP39 test vector — not a real wallet
+    private val testMnemonic =
+        "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong"
+
+    // ============================================================
+    // Type construction
+    // ============================================================
+
+    @Test
+    fun invoice_status_enum_values() {
+        assertNotNull(InvoiceStatus.UNPAID)
+        assertNotNull(InvoiceStatus.PAID)
+        assertNotNull(InvoiceStatus.EXPIRED)
+    }
+
+    @Test
+    fun payment_direction_enum_values() {
+        assertNotNull(PaymentDirection.SENT)
+        assertNotNull(PaymentDirection.RECEIVED)
+    }
+
+    @Test
+    fun payment_status_enum_values() {
+        assertNotNull(PaymentStatus.PENDING)
+        assertNotNull(PaymentStatus.COMPLETE)
+        assertNotNull(PaymentStatus.FAILED)
+        assertNotNull(PaymentStatus.EXPIRED)
+    }
+
+    // ============================================================
+    // Invoice appears in list_invoices and list_payments
+    // ============================================================
+
+    @OptIn(ExperimentalUuidApi::class)
+    @Test
+    fun created_invoice_appears_in_list_invoices() {
+        val config = Config()
+        registerOrRecover(testMnemonic, null, config).use { node ->
+            val label = Uuid.random().toString()
+            node.receive(label = label, description = "Coffee", amountMsat = 10_000_000uL)
+
+            val result = node.listInvoices()
+            val matching = result.invoices.filter { it.label == label }
+            assertEquals("Should find exactly one invoice", 1, matching.size)
+            assertEquals(InvoiceStatus.UNPAID, matching[0].status)
+            assertEquals("Coffee", matching[0].description)
+            assertNotNull(matching[0].bolt11)
+        }
+    }
+
+    @OptIn(ExperimentalUuidApi::class)
+    @Test
+    fun default_filter_excludes_unpaid() {
+        val config = Config()
+        registerOrRecover(testMnemonic, null, config).use { node ->
+            val label = Uuid.random().toString()
+            node.receive(label = label, description = "Tea", amountMsat = 5_000_000uL)
+
+            // Default (null) filters to COMPLETE, so unpaid invoice should not appear
+            val result = node.listPayments()
+            val matching = result.payments.filter { it.label == label }
+            assertTrue("Default filter should exclude UNPAID invoice", matching.isEmpty())
+        }
+    }
+
+    @OptIn(ExperimentalUuidApi::class)
+    @Test
+    fun pending_filter_includes_unpaid_invoice() {
+        val config = Config()
+        registerOrRecover(testMnemonic, null, config).use { node ->
+            val label = Uuid.random().toString()
+            node.receive(label = label, description = "Tea", amountMsat = 5_000_000uL)
+
+            val result = node.listPayments(PaymentStatus.PENDING)
+            val matching = result.payments.filter { it.label == label }
+            assertEquals("PENDING filter should include UNPAID invoice", 1, matching.size)
+            assertEquals(PaymentDirection.RECEIVED, matching[0].direction)
+            assertEquals(PaymentStatus.PENDING, matching[0].status)
+            assertEquals(InvoiceStatus.UNPAID, matching[0].invoiceStatus)
+            assertNull(matching[0].payStatus)
+            assertNotNull(matching[0].invoice)
+            assertEquals(label, matching[0].invoice?.label)
+            assertNull(matching[0].pay)
+        }
+    }
+}

docs/superpowers/specs/2026-04-01-list-payments-api-design.md

@@ -0,0 +1,31 @@
+// Kotlin extension functions for Node that provide default parameter values.
+// The UniFFI-generated bindings require all parameters explicitly;
+// these extensions give Kotlin consumers idiomatic optional-parameter APIs.
+
+package com.blockstream.glsdk
+
+@Throws(Exception::class)
+public fun Node.listInvoices(
+    label: String? = null,
+    invstring: String? = null,
+    paymentHash: ByteArray? = null,
+    offerId: String? = null,
+    index: ListIndex? = null,
+    start: ULong? = null,
+    limit: UInt? = null,
+): ListInvoicesResponse = listInvoices(label, invstring, paymentHash, offerId, index, start, limit)
+
+@Throws(Exception::class)
+public fun Node.listPays(
+    bolt11: String? = null,
+    paymentHash: ByteArray? = null,
+    status: PayStatus? = null,
+    index: ListIndex? = null,
+    start: ULong? = null,
+    limit: UInt? = null,
+): ListPaysResponse = listPays(bolt11, paymentHash, status, index, start, limit)
+
+@Throws(Exception::class)
+public fun Node.listPayments(
+    status: PaymentStatus? = null,
+): ListPaymentsResponse = listPayments(status)

libs/gl-sdk-android/lib/src/androidInstrumentedTest/kotlin/com/blockstream/glsdk/ListPaymentTest.kt

@@ -35,10 +35,12 @@ pub use crate::{
     config::Config,
     credentials::{Credentials, DeveloperCert},
     node::{
-        ChannelState, FundChannel, FundOutput, GetInfoResponse, InvoicePaidEvent,
-        ListFundsResponse, ListPeerChannelsResponse, ListPeersResponse, Node, NodeEvent,
-        NodeEventStream, OnchainReceiveResponse, OnchainSendResponse, OutputStatus, PayStatus,
-        Peer, PeerChannel, ReceiveResponse, SendResponse,
+        ChannelState, FundChannel, FundOutput, GetInfoResponse, Invoice, InvoicePaidEvent,
+        InvoiceStatus, ListFundsResponse, ListIndex, ListInvoicesResponse, ListPaymentsResponse,
+        ListPeerChannelsResponse, ListPaysResponse, ListPeersResponse, Node, NodeEvent,
+        NodeEventStream, OnchainReceiveResponse, OnchainSendResponse, OutputStatus, Pay,
+        PayStatus, Payment, PaymentDirection, PaymentStatus, Peer, PeerChannel, ReceiveResponse,
+        SendResponse,
     },
     scheduler::Scheduler,
     signer::{Handle, Signer},