11/**
22 * Lightning Module for CoinPay SDK
33 *
4- * Manages BOLT12 Lightning Network operations: node provisioning,
5- * offer creation, and payment tracking.
4+ * Manages Lightning Network operations: wallet provisioning (via LNbits),
5+ * lightning address registration, invoice creation, payment sending, and history.
6+ *
7+ * Lightning wallets are custodial — funds are held on CoinPay's server.
68 */
79
8- const DEFAULT_BASE_URL = 'https://coinpayportal.com/api' ;
9-
1010/**
11- * Lightning client for BOLT12 operations
11+ * Lightning client for LN operations
1212 */
1313export class LightningClient {
1414 #client;
@@ -21,24 +21,31 @@ export class LightningClient {
2121 }
2222
2323 // ──────────────────────────────────────────────
24- // Nodes
24+ // Nodes / Wallet Provisioning
2525 // ──────────────────────────────────────────────
2626
2727 /**
28- * Provision a Greenlight CLN node for a wallet.
28+ * Enable Lightning for a wallet (provisions an LNbits custodial wallet) .
2929 * @param {Object } params
3030 * @param {string } params.wallet_id - Wallet UUID
31- * @param {string } params.mnemonic - BIP39 mnemonic (used server-side to derive LN keys)
31+ * @param {string } params.mnemonic - BIP39 mnemonic
3232 * @param {string } [params.business_id] - Optional business UUID
33- * @returns {Promise<Object> } The provisioned node
33+ * @returns {Promise<Object> } The provisioned node record
3434 */
35- async provisionNode ( { wallet_id, mnemonic, business_id } ) {
35+ async enableWallet ( { wallet_id, mnemonic, business_id } ) {
3636 return this . #client. request ( '/lightning/nodes' , {
3737 method : 'POST' ,
3838 body : JSON . stringify ( { wallet_id, mnemonic, business_id } ) ,
3939 } ) ;
4040 }
4141
42+ /**
43+ * @deprecated Use enableWallet() instead
44+ */
45+ async provisionNode ( params ) {
46+ return this . enableWallet ( params ) ;
47+ }
48+
4249 /**
4350 * Get node status by ID.
4451 * @param {string } nodeId
@@ -58,31 +65,81 @@ export class LightningClient {
5865 }
5966
6067 // ──────────────────────────────────────────────
61- // Offers
68+ // Lightning Address
6269 // ──────────────────────────────────────────────
6370
6471 /**
65- * Create a BOLT12 offer.
72+ * Register a Lightning Address (username@coinpayportal.com).
73+ * Requires Lightning to be enabled first.
6674 * @param {Object } params
67- * @param {string } params.wallet_id - Wallet UUID (required for wallet ownership checks)
68- * @param {string } params.node_id - Node UUID
69- * @param {string } params.description - Human-readable description
70- * @param {number } [params.amount_msat] - Fixed amount in millisatoshis (omit for any-amount)
71- * @param {string } [params.currency] - Currency code (default: "BTC")
72- * @param {string } [params.business_id] - Optional business UUID
73- * @returns {Promise<Object> }
75+ * @param {string } params.wallet_id - Wallet UUID
76+ * @param {string } params.username - Desired username (3-32 chars, lowercase alphanumeric)
77+ * @returns {Promise<Object> } { lightning_address, username }
78+ */
79+ async registerAddress ( { wallet_id, username } ) {
80+ return this . #client. request ( '/lightning/address' , {
81+ method : 'POST' ,
82+ body : JSON . stringify ( { wallet_id, username } ) ,
83+ } ) ;
84+ }
85+
86+ /**
87+ * Get Lightning Address for a wallet.
88+ * @param {string } walletId - Wallet UUID
89+ * @returns {Promise<Object> } { lightning_address, username } or { lightning_address: null }
90+ */
91+ async getAddress ( walletId ) {
92+ return this . #client. request ( `/lightning/address?wallet_id=${ walletId } ) ;
93+ }
94+
95+ /**
96+ * Check if a Lightning Address username is available.
97+ * @param {string } username
98+ * @returns {Promise<Object> } { available: boolean }
99+ */
100+ async checkAddressAvailable ( username ) {
101+ return this . #client. request ( `/lightning/address?username=${ encodeURIComponent ( username ) } ) ;
102+ }
103+
104+ // ──────────────────────────────────────────────
105+ // Invoices
106+ // ──────────────────────────────────────────────
107+
108+ /**
109+ * Create a BOLT11 invoice to receive a payment.
110+ * @param {Object } params
111+ * @param {string } params.wallet_id - Wallet UUID
112+ * @param {number } params.amount_sats - Amount in satoshis
113+ * @param {string } [params.description] - Invoice description/memo
114+ * @returns {Promise<Object> } { payment_request, payment_hash, ... }
74115 */
75- async createOffer ( { wallet_id, node_id, description, amount_msat, currency, business_id } ) {
116+ async createInvoice ( { wallet_id, amount_sats, description } ) {
117+ return this . #client. request ( '/lightning/invoices' , {
118+ method : 'POST' ,
119+ body : JSON . stringify ( { wallet_id, amount_sats, description } ) ,
120+ } ) ;
121+ }
122+
123+ // ──────────────────────────────────────────────
124+ // Offers (BOLT12) — currently not supported
125+ // ──────────────────────────────────────────────
126+
127+ /**
128+ * Create a BOLT12 offer.
129+ * @deprecated BOLT12 offers are not currently supported (LNbits limitation).
130+ * Use createInvoice() or registerAddress() instead.
131+ */
132+ async createOffer ( params ) {
76133 return this . #client. request ( '/lightning/offers' , {
77134 method : 'POST' ,
78- body : JSON . stringify ( { wallet_id , node_id , description , amount_msat , currency , business_id } ) ,
135+ body : JSON . stringify ( params ) ,
79136 } ) ;
80137 }
81138
82139 /**
83140 * Get offer by ID.
84141 * @param {string } offerId
85- * @returns {Promise<Object> } Includes offer and qr_uri
142+ * @returns {Promise<Object> }
86143 */
87144 async getOffer ( offerId ) {
88145 return this . #client. request ( `/lightning/offers/${ offerId } ) ;
@@ -93,9 +150,9 @@ export class LightningClient {
93150 * @param {Object } [params]
94151 * @param {string } [params.business_id]
95152 * @param {string } [params.node_id]
96- * @param {string } [params.status] - "active" | "disabled" | "archived"
97- * @param {number } [params.limit] - Default 20
98- * @param {number } [params.offset] - Default 0
153+ * @param {string } [params.status]
154+ * @param {number } [params.limit]
155+ * @param {number } [params.offset]
99156 * @returns {Promise<Object> } { offers, total, limit, offset }
100157 */
101158 async listOffers ( params = { } ) {
@@ -110,12 +167,31 @@ export class LightningClient {
110167 // Payments
111168 // ──────────────────────────────────────────────
112169
170+ /**
171+ * Send a Lightning payment. Accepts:
172+ * - BOLT11 invoice string
173+ * - Lightning address (user@domain)
174+ * @param {Object } params
175+ * @param {string } params.wallet_id - Wallet UUID
176+ * @param {string } params.destination - BOLT11 invoice or lightning address (user@domain)
177+ * @param {number } [params.amount_sats] - Amount in satoshis (required for lightning addresses, optional for invoices with amount)
178+ * @returns {Promise<Object> } { payment_hash, status }
179+ */
180+ async sendPayment ( { wallet_id, destination, amount_sats } ) {
181+ return this . #client. request ( '/lightning/payments' , {
182+ method : 'POST' ,
183+ body : JSON . stringify ( { wallet_id, bolt12 : destination , amount_sats } ) ,
184+ } ) ;
185+ }
186+
113187 /**
114188 * List Lightning payments.
115189 * @param {Object } [params]
190+ * @param {string } [params.wallet_id]
116191 * @param {string } [params.business_id]
117192 * @param {string } [params.node_id]
118193 * @param {string } [params.offer_id]
194+ * @param {string } [params.direction] - "incoming" | "outgoing"
119195 * @param {string } [params.status] - "pending" | "settled" | "failed"
120196 * @param {number } [params.limit] - Default 50
121197 * @param {number } [params.offset] - Default 0
@@ -129,22 +205,6 @@ export class LightningClient {
129205 return this . #client. request ( `/lightning/payments?${ qs } ) ;
130206 }
131207
132- /**
133- * Send a payment to a BOLT12 offer or invoice.
134- * @param {Object } params
135- * @param {string } params.wallet_id - Wallet UUID (required for wallet ownership checks)
136- * @param {string } params.node_id - Node UUID
137- * @param {string } params.bolt12 - BOLT12 offer or invoice string
138- * @param {number } params.amount_sats - Amount in satoshis
139- * @returns {Promise<Object> }
140- */
141- async sendPayment ( { wallet_id, node_id, bolt12, amount_sats } ) {
142- return this . #client. request ( '/lightning/payments' , {
143- method : 'POST' ,
144- body : JSON . stringify ( { wallet_id, node_id, bolt12, amount_sats } ) ,
145- } ) ;
146- }
147-
148208 /**
149209 * Get payment status by payment hash.
150210 * @param {string } paymentHash
0 commit comments