@getalby/lightning-tools 8.1.1 → 8.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +78 -13
- package/dist/cjs/402/l402.cjs +1304 -2
- package/dist/cjs/402/l402.cjs.map +1 -1
- package/dist/cjs/402/mpp.cjs +1306 -5
- package/dist/cjs/402/mpp.cjs.map +1 -1
- package/dist/cjs/402/x402.cjs +46 -15
- package/dist/cjs/402/x402.cjs.map +1 -1
- package/dist/cjs/402.cjs +101 -10
- package/dist/cjs/402.cjs.map +1 -1
- package/dist/cjs/bip21.cjs +115 -0
- package/dist/cjs/bip21.cjs.map +1 -0
- package/dist/cjs/index.cjs +213 -10
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/402/l402.js +1304 -2
- package/dist/esm/402/l402.js.map +1 -1
- package/dist/esm/402/mpp.js +1306 -5
- package/dist/esm/402/mpp.js.map +1 -1
- package/dist/esm/402/x402.js +46 -15
- package/dist/esm/402/x402.js.map +1 -1
- package/dist/esm/402.js +98 -11
- package/dist/esm/402.js.map +1 -1
- package/dist/esm/bip21.js +112 -0
- package/dist/esm/bip21.js.map +1 -0
- package/dist/esm/index.js +208 -11
- package/dist/esm/index.js.map +1 -1
- package/dist/lightning-tools.umd.js +2 -2
- package/dist/lightning-tools.umd.js.map +1 -1
- package/dist/types/402/l402.d.ts +49 -3
- package/dist/types/402/mpp.d.ts +54 -6
- package/dist/types/402/x402.d.ts +49 -3
- package/dist/types/402.d.ts +68 -17
- package/dist/types/bip21.d.ts +46 -0
- package/dist/types/index.d.ts +112 -17
- package/package.json +6 -1
package/dist/types/402/l402.d.ts
CHANGED
|
@@ -3,12 +3,58 @@ interface Wallet {
|
|
|
3
3
|
invoice: string;
|
|
4
4
|
}): Promise<{
|
|
5
5
|
preimage: string;
|
|
6
|
+
fees_paid?: number;
|
|
6
7
|
}>;
|
|
7
8
|
}
|
|
8
|
-
|
|
9
|
-
|
|
9
|
+
/**
|
|
10
|
+
* A reusable payment credential. After a successful paid request the credential
|
|
11
|
+
* is attached to the response (see {@link PaymentInfo}). Pass it back via
|
|
12
|
+
* `options.credentials` on a follow-up request (e.g. polling a long-running
|
|
13
|
+
* job) to authorize the request without paying again.
|
|
14
|
+
*
|
|
15
|
+
* `header` is the HTTP header the credential is sent in (`Authorization` for
|
|
16
|
+
* L402/MPP, `payment-signature` for x402) and `value` is the header value.
|
|
17
|
+
*/
|
|
18
|
+
interface PaymentCredentials {
|
|
19
|
+
header: string;
|
|
20
|
+
value: string;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Payment metadata attached (as `response.payment`) to responses returned by
|
|
24
|
+
* the 402 fetch helpers.
|
|
25
|
+
*/
|
|
26
|
+
interface PaymentInfo {
|
|
27
|
+
/** Whether a lightning payment was made to obtain this response. */
|
|
28
|
+
paid: boolean;
|
|
29
|
+
/** Amount of the paid invoice, in satoshis (0 when `paid` is false). */
|
|
30
|
+
amount: number;
|
|
31
|
+
/** Routing fees paid, in millisatoshis, when reported by the wallet. */
|
|
32
|
+
feesPaid?: number;
|
|
33
|
+
/** Payment preimage, present when a payment was made. */
|
|
34
|
+
preimage?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Reusable credential. Pass it back via `options.credentials` on a follow-up
|
|
37
|
+
* request (e.g. polling) to authorize it without paying again.
|
|
38
|
+
*/
|
|
39
|
+
credentials: PaymentCredentials;
|
|
40
|
+
}
|
|
41
|
+
/** A `Response` with optional payment metadata attached by the 402 helpers. */
|
|
42
|
+
type PaidResponse = Response & {
|
|
43
|
+
payment?: PaymentInfo;
|
|
44
|
+
};
|
|
45
|
+
/** Options accepted by the 402 fetch helpers. */
|
|
46
|
+
interface Fetch402Options {
|
|
10
47
|
wallet: Wallet;
|
|
11
|
-
|
|
48
|
+
/**
|
|
49
|
+
* A credential returned by a previous paid request. When provided it is
|
|
50
|
+
* applied to the request and the helper NEVER pays again — even if the server
|
|
51
|
+
* still responds with a 402 (that response is returned to the caller as-is).
|
|
52
|
+
* Use it to authorize follow-up requests (e.g. polling) without re-paying.
|
|
53
|
+
*/
|
|
54
|
+
credentials?: PaymentCredentials;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
12
58
|
|
|
13
59
|
interface WwwAuthenticatePayload {
|
|
14
60
|
token: string;
|
package/dist/types/402/mpp.d.ts
CHANGED
|
@@ -3,8 +3,56 @@ interface Wallet {
|
|
|
3
3
|
invoice: string;
|
|
4
4
|
}): Promise<{
|
|
5
5
|
preimage: string;
|
|
6
|
+
fees_paid?: number;
|
|
6
7
|
}>;
|
|
7
8
|
}
|
|
9
|
+
/**
|
|
10
|
+
* A reusable payment credential. After a successful paid request the credential
|
|
11
|
+
* is attached to the response (see {@link PaymentInfo}). Pass it back via
|
|
12
|
+
* `options.credentials` on a follow-up request (e.g. polling a long-running
|
|
13
|
+
* job) to authorize the request without paying again.
|
|
14
|
+
*
|
|
15
|
+
* `header` is the HTTP header the credential is sent in (`Authorization` for
|
|
16
|
+
* L402/MPP, `payment-signature` for x402) and `value` is the header value.
|
|
17
|
+
*/
|
|
18
|
+
interface PaymentCredentials {
|
|
19
|
+
header: string;
|
|
20
|
+
value: string;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Payment metadata attached (as `response.payment`) to responses returned by
|
|
24
|
+
* the 402 fetch helpers.
|
|
25
|
+
*/
|
|
26
|
+
interface PaymentInfo {
|
|
27
|
+
/** Whether a lightning payment was made to obtain this response. */
|
|
28
|
+
paid: boolean;
|
|
29
|
+
/** Amount of the paid invoice, in satoshis (0 when `paid` is false). */
|
|
30
|
+
amount: number;
|
|
31
|
+
/** Routing fees paid, in millisatoshis, when reported by the wallet. */
|
|
32
|
+
feesPaid?: number;
|
|
33
|
+
/** Payment preimage, present when a payment was made. */
|
|
34
|
+
preimage?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Reusable credential. Pass it back via `options.credentials` on a follow-up
|
|
37
|
+
* request (e.g. polling) to authorize it without paying again.
|
|
38
|
+
*/
|
|
39
|
+
credentials: PaymentCredentials;
|
|
40
|
+
}
|
|
41
|
+
/** A `Response` with optional payment metadata attached by the 402 helpers. */
|
|
42
|
+
type PaidResponse = Response & {
|
|
43
|
+
payment?: PaymentInfo;
|
|
44
|
+
};
|
|
45
|
+
/** Options accepted by the 402 fetch helpers. */
|
|
46
|
+
interface Fetch402Options {
|
|
47
|
+
wallet: Wallet;
|
|
48
|
+
/**
|
|
49
|
+
* A credential returned by a previous paid request. When provided it is
|
|
50
|
+
* applied to the request and the helper NEVER pays again — even if the server
|
|
51
|
+
* still responds with a 402 (that response is returned to the caller as-is).
|
|
52
|
+
* Use it to authorize follow-up requests (e.g. polling) without re-paying.
|
|
53
|
+
*/
|
|
54
|
+
credentials?: PaymentCredentials;
|
|
55
|
+
}
|
|
8
56
|
|
|
9
57
|
/**
|
|
10
58
|
* Fetch a resource protected by the draft-lightning-charge-00 payment
|
|
@@ -15,12 +63,12 @@ interface Wallet {
|
|
|
15
63
|
* the function pays the embedded BOLT11 invoice and retries with the
|
|
16
64
|
* resulting preimage as the credential.
|
|
17
65
|
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
66
|
+
* Pass a previous credential via `options.credentials` to reuse it (e.g. when
|
|
67
|
+
* polling); the credential is applied and the function NEVER pays again, even
|
|
68
|
+
* if the server still responds with a 402 (that response is returned as-is).
|
|
69
|
+
* Note: lightning-charge typically uses consume-once challenge semantics, so a
|
|
70
|
+
* reused credential is only accepted by servers that explicitly support it.
|
|
21
71
|
*/
|
|
22
|
-
declare const fetchWithMpp: (url: string, fetchArgs: RequestInit, options:
|
|
23
|
-
wallet: Wallet;
|
|
24
|
-
}) => Promise<Response>;
|
|
72
|
+
declare const fetchWithMpp: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
25
73
|
|
|
26
74
|
export { fetchWithMpp };
|
package/dist/types/402/x402.d.ts
CHANGED
|
@@ -3,8 +3,56 @@ interface Wallet {
|
|
|
3
3
|
invoice: string;
|
|
4
4
|
}): Promise<{
|
|
5
5
|
preimage: string;
|
|
6
|
+
fees_paid?: number;
|
|
6
7
|
}>;
|
|
7
8
|
}
|
|
9
|
+
/**
|
|
10
|
+
* A reusable payment credential. After a successful paid request the credential
|
|
11
|
+
* is attached to the response (see {@link PaymentInfo}). Pass it back via
|
|
12
|
+
* `options.credentials` on a follow-up request (e.g. polling a long-running
|
|
13
|
+
* job) to authorize the request without paying again.
|
|
14
|
+
*
|
|
15
|
+
* `header` is the HTTP header the credential is sent in (`Authorization` for
|
|
16
|
+
* L402/MPP, `payment-signature` for x402) and `value` is the header value.
|
|
17
|
+
*/
|
|
18
|
+
interface PaymentCredentials {
|
|
19
|
+
header: string;
|
|
20
|
+
value: string;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Payment metadata attached (as `response.payment`) to responses returned by
|
|
24
|
+
* the 402 fetch helpers.
|
|
25
|
+
*/
|
|
26
|
+
interface PaymentInfo {
|
|
27
|
+
/** Whether a lightning payment was made to obtain this response. */
|
|
28
|
+
paid: boolean;
|
|
29
|
+
/** Amount of the paid invoice, in satoshis (0 when `paid` is false). */
|
|
30
|
+
amount: number;
|
|
31
|
+
/** Routing fees paid, in millisatoshis, when reported by the wallet. */
|
|
32
|
+
feesPaid?: number;
|
|
33
|
+
/** Payment preimage, present when a payment was made. */
|
|
34
|
+
preimage?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Reusable credential. Pass it back via `options.credentials` on a follow-up
|
|
37
|
+
* request (e.g. polling) to authorize it without paying again.
|
|
38
|
+
*/
|
|
39
|
+
credentials: PaymentCredentials;
|
|
40
|
+
}
|
|
41
|
+
/** A `Response` with optional payment metadata attached by the 402 helpers. */
|
|
42
|
+
type PaidResponse = Response & {
|
|
43
|
+
payment?: PaymentInfo;
|
|
44
|
+
};
|
|
45
|
+
/** Options accepted by the 402 fetch helpers. */
|
|
46
|
+
interface Fetch402Options {
|
|
47
|
+
wallet: Wallet;
|
|
48
|
+
/**
|
|
49
|
+
* A credential returned by a previous paid request. When provided it is
|
|
50
|
+
* applied to the request and the helper NEVER pays again — even if the server
|
|
51
|
+
* still responds with a 402 (that response is returned to the caller as-is).
|
|
52
|
+
* Use it to authorize follow-up requests (e.g. polling) without re-paying.
|
|
53
|
+
*/
|
|
54
|
+
credentials?: PaymentCredentials;
|
|
55
|
+
}
|
|
8
56
|
|
|
9
57
|
interface X402Requirements {
|
|
10
58
|
scheme: string;
|
|
@@ -25,8 +73,6 @@ interface X402Requirements {
|
|
|
25
73
|
* the 402 back to the caller.
|
|
26
74
|
*/
|
|
27
75
|
declare const findX402LightningRequirements: (x402Header: string) => X402Requirements | null;
|
|
28
|
-
declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options:
|
|
29
|
-
wallet: Wallet;
|
|
30
|
-
}) => Promise<Response>;
|
|
76
|
+
declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
31
77
|
|
|
32
78
|
export { fetchWithX402, findX402LightningRequirements };
|
package/dist/types/402.d.ts
CHANGED
|
@@ -3,18 +3,71 @@ interface Wallet {
|
|
|
3
3
|
invoice: string;
|
|
4
4
|
}): Promise<{
|
|
5
5
|
preimage: string;
|
|
6
|
+
fees_paid?: number;
|
|
6
7
|
}>;
|
|
7
8
|
}
|
|
9
|
+
/**
|
|
10
|
+
* A reusable payment credential. After a successful paid request the credential
|
|
11
|
+
* is attached to the response (see {@link PaymentInfo}). Pass it back via
|
|
12
|
+
* `options.credentials` on a follow-up request (e.g. polling a long-running
|
|
13
|
+
* job) to authorize the request without paying again.
|
|
14
|
+
*
|
|
15
|
+
* `header` is the HTTP header the credential is sent in (`Authorization` for
|
|
16
|
+
* L402/MPP, `payment-signature` for x402) and `value` is the header value.
|
|
17
|
+
*/
|
|
18
|
+
interface PaymentCredentials {
|
|
19
|
+
header: string;
|
|
20
|
+
value: string;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Payment metadata attached (as `response.payment`) to responses returned by
|
|
24
|
+
* the 402 fetch helpers.
|
|
25
|
+
*/
|
|
26
|
+
interface PaymentInfo {
|
|
27
|
+
/** Whether a lightning payment was made to obtain this response. */
|
|
28
|
+
paid: boolean;
|
|
29
|
+
/** Amount of the paid invoice, in satoshis (0 when `paid` is false). */
|
|
30
|
+
amount: number;
|
|
31
|
+
/** Routing fees paid, in millisatoshis, when reported by the wallet. */
|
|
32
|
+
feesPaid?: number;
|
|
33
|
+
/** Payment preimage, present when a payment was made. */
|
|
34
|
+
preimage?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Reusable credential. Pass it back via `options.credentials` on a follow-up
|
|
37
|
+
* request (e.g. polling) to authorize it without paying again.
|
|
38
|
+
*/
|
|
39
|
+
credentials: PaymentCredentials;
|
|
40
|
+
}
|
|
41
|
+
/** A `Response` with optional payment metadata attached by the 402 helpers. */
|
|
42
|
+
type PaidResponse = Response & {
|
|
43
|
+
payment?: PaymentInfo;
|
|
44
|
+
};
|
|
45
|
+
/** Options accepted by the 402 fetch helpers. */
|
|
46
|
+
interface Fetch402Options {
|
|
47
|
+
wallet: Wallet;
|
|
48
|
+
/**
|
|
49
|
+
* A credential returned by a previous paid request. When provided it is
|
|
50
|
+
* applied to the request and the helper NEVER pays again — even if the server
|
|
51
|
+
* still responds with a 402 (that response is returned to the caller as-is).
|
|
52
|
+
* Use it to authorize follow-up requests (e.g. polling) without re-paying.
|
|
53
|
+
*/
|
|
54
|
+
credentials?: PaymentCredentials;
|
|
55
|
+
}
|
|
56
|
+
/** Apply a previously-obtained credential to the outgoing request headers. */
|
|
57
|
+
declare const applyCredentials: (headers: Headers, credentials: PaymentCredentials) => void;
|
|
58
|
+
/** Attach payment metadata to a response and return it (typed). */
|
|
59
|
+
declare const attachPayment: (response: Response, payment: PaymentInfo | undefined) => PaidResponse;
|
|
60
|
+
/** Payment metadata describing a request authorized with a reused credential. */
|
|
61
|
+
declare const reusedCredentialPayment: (credentials: PaymentCredentials | undefined) => PaymentInfo | undefined;
|
|
62
|
+
/** Satoshi amount of a BOLT11 invoice (0 when it cannot be decoded). */
|
|
63
|
+
declare const getInvoiceAmount: (invoice: string) => number;
|
|
8
64
|
declare function createGuardedWallet(wallet: Wallet, maxAmountSats: number): Wallet;
|
|
9
65
|
|
|
10
|
-
declare const fetch402: (url: string, fetchArgs: RequestInit, options: {
|
|
11
|
-
wallet: Wallet;
|
|
66
|
+
declare const fetch402: (url: string, fetchArgs: RequestInit, options: Fetch402Options & {
|
|
12
67
|
maxAmount?: number;
|
|
13
|
-
}) => Promise<
|
|
68
|
+
}) => Promise<PaidResponse>;
|
|
14
69
|
|
|
15
|
-
declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options:
|
|
16
|
-
wallet: Wallet;
|
|
17
|
-
}) => Promise<Response>;
|
|
70
|
+
declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
18
71
|
|
|
19
72
|
interface WwwAuthenticatePayload {
|
|
20
73
|
token: string;
|
|
@@ -72,9 +125,7 @@ interface X402Requirements {
|
|
|
72
125
|
* the 402 back to the caller.
|
|
73
126
|
*/
|
|
74
127
|
declare const findX402LightningRequirements: (x402Header: string) => X402Requirements | null;
|
|
75
|
-
declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options:
|
|
76
|
-
wallet: Wallet;
|
|
77
|
-
}) => Promise<Response>;
|
|
128
|
+
declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
78
129
|
|
|
79
130
|
/**
|
|
80
131
|
* Fetch a resource protected by the draft-lightning-charge-00 payment
|
|
@@ -85,13 +136,13 @@ declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: {
|
|
|
85
136
|
* the function pays the embedded BOLT11 invoice and retries with the
|
|
86
137
|
* resulting preimage as the credential.
|
|
87
138
|
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
90
|
-
*
|
|
139
|
+
* Pass a previous credential via `options.credentials` to reuse it (e.g. when
|
|
140
|
+
* polling); the credential is applied and the function NEVER pays again, even
|
|
141
|
+
* if the server still responds with a 402 (that response is returned as-is).
|
|
142
|
+
* Note: lightning-charge typically uses consume-once challenge semantics, so a
|
|
143
|
+
* reused credential is only accepted by servers that explicitly support it.
|
|
91
144
|
*/
|
|
92
|
-
declare const fetchWithMpp: (url: string, fetchArgs: RequestInit, options:
|
|
93
|
-
wallet: Wallet;
|
|
94
|
-
}) => Promise<Response>;
|
|
145
|
+
declare const fetchWithMpp: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
95
146
|
|
|
96
|
-
export { createGuardedWallet, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, findX402LightningRequirements, issueL402Macaroon, makeL402AuthenticateHeader, parseL402, parseL402Authorization, verifyL402Macaroon };
|
|
97
|
-
export type { MacaroonPayload, Wallet };
|
|
147
|
+
export { applyCredentials, attachPayment, createGuardedWallet, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, findX402LightningRequirements, getInvoiceAmount, issueL402Macaroon, makeL402AuthenticateHeader, parseL402, parseL402Authorization, reusedCredentialPayment, verifyL402Macaroon };
|
|
148
|
+
export type { Fetch402Options, MacaroonPayload, PaidResponse, PaymentCredentials, PaymentInfo, Wallet };
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
type Bip21 = {
|
|
2
|
+
/** Bare on-chain bitcoin address (no scheme, no query string). */
|
|
3
|
+
address: string;
|
|
4
|
+
/** Requested amount in BTC, as defined by BIP21 (e.g. 0.01). */
|
|
5
|
+
amount?: number;
|
|
6
|
+
/** Requested amount converted to satoshis, for convenience. */
|
|
7
|
+
amountSats?: number;
|
|
8
|
+
/** Label for the recipient, decoded. */
|
|
9
|
+
label?: string;
|
|
10
|
+
/** Free-form message, decoded. */
|
|
11
|
+
message?: string;
|
|
12
|
+
/** BOLT11 invoice or LNURL, from the `lightning=` parameter (unified QR). */
|
|
13
|
+
lightning?: string;
|
|
14
|
+
/** BOLT12 offer, from the `lno=` parameter. */
|
|
15
|
+
lno?: string;
|
|
16
|
+
/**
|
|
17
|
+
* `req-*` parameters that the client doesn't know how to handle.
|
|
18
|
+
* Per BIP21, callers MUST reject the URI if this is non-empty.
|
|
19
|
+
*/
|
|
20
|
+
unknownRequiredParams: string[];
|
|
21
|
+
/** All query parameters, decoded, for advanced/custom use. */
|
|
22
|
+
params: Record<string, string>;
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Parse a BIP21 (`bitcoin:`) URI. Returns `null` if the input doesn't have the
|
|
27
|
+
* `bitcoin:` scheme.
|
|
28
|
+
*
|
|
29
|
+
* The address is returned as-is (case preserved) — callers should validate it
|
|
30
|
+
* separately if they need to ensure it's a well-formed bitcoin address.
|
|
31
|
+
*
|
|
32
|
+
* Per BIP21, parameters prefixed with `req-` are required: if the client
|
|
33
|
+
* doesn't understand any of them, the payment MUST NOT be made. The unknown
|
|
34
|
+
* required params are surfaced via `unknownRequiredParams` so callers can
|
|
35
|
+
* decide how to fail.
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* parseBip21("bitcoin:bc1q...?amount=0.001&lightning=lnbc...")
|
|
39
|
+
* // => { address: "bc1q...", amount: 0.001, amountSats: 100000, lightning: "lnbc...", ... }
|
|
40
|
+
*/
|
|
41
|
+
declare const parseBip21: (uri: string) => Bip21 | null;
|
|
42
|
+
/** Returns true if the input starts with the `bitcoin:` URI scheme. */
|
|
43
|
+
declare const isBip21: (uri: string) => boolean;
|
|
44
|
+
|
|
45
|
+
export { isBip21, parseBip21 };
|
|
46
|
+
export type { Bip21 };
|
package/dist/types/index.d.ts
CHANGED
|
@@ -245,18 +245,71 @@ interface Wallet {
|
|
|
245
245
|
invoice: string;
|
|
246
246
|
}): Promise<{
|
|
247
247
|
preimage: string;
|
|
248
|
+
fees_paid?: number;
|
|
248
249
|
}>;
|
|
249
250
|
}
|
|
251
|
+
/**
|
|
252
|
+
* A reusable payment credential. After a successful paid request the credential
|
|
253
|
+
* is attached to the response (see {@link PaymentInfo}). Pass it back via
|
|
254
|
+
* `options.credentials` on a follow-up request (e.g. polling a long-running
|
|
255
|
+
* job) to authorize the request without paying again.
|
|
256
|
+
*
|
|
257
|
+
* `header` is the HTTP header the credential is sent in (`Authorization` for
|
|
258
|
+
* L402/MPP, `payment-signature` for x402) and `value` is the header value.
|
|
259
|
+
*/
|
|
260
|
+
interface PaymentCredentials {
|
|
261
|
+
header: string;
|
|
262
|
+
value: string;
|
|
263
|
+
}
|
|
264
|
+
/**
|
|
265
|
+
* Payment metadata attached (as `response.payment`) to responses returned by
|
|
266
|
+
* the 402 fetch helpers.
|
|
267
|
+
*/
|
|
268
|
+
interface PaymentInfo {
|
|
269
|
+
/** Whether a lightning payment was made to obtain this response. */
|
|
270
|
+
paid: boolean;
|
|
271
|
+
/** Amount of the paid invoice, in satoshis (0 when `paid` is false). */
|
|
272
|
+
amount: number;
|
|
273
|
+
/** Routing fees paid, in millisatoshis, when reported by the wallet. */
|
|
274
|
+
feesPaid?: number;
|
|
275
|
+
/** Payment preimage, present when a payment was made. */
|
|
276
|
+
preimage?: string;
|
|
277
|
+
/**
|
|
278
|
+
* Reusable credential. Pass it back via `options.credentials` on a follow-up
|
|
279
|
+
* request (e.g. polling) to authorize it without paying again.
|
|
280
|
+
*/
|
|
281
|
+
credentials: PaymentCredentials;
|
|
282
|
+
}
|
|
283
|
+
/** A `Response` with optional payment metadata attached by the 402 helpers. */
|
|
284
|
+
type PaidResponse = Response & {
|
|
285
|
+
payment?: PaymentInfo;
|
|
286
|
+
};
|
|
287
|
+
/** Options accepted by the 402 fetch helpers. */
|
|
288
|
+
interface Fetch402Options {
|
|
289
|
+
wallet: Wallet;
|
|
290
|
+
/**
|
|
291
|
+
* A credential returned by a previous paid request. When provided it is
|
|
292
|
+
* applied to the request and the helper NEVER pays again — even if the server
|
|
293
|
+
* still responds with a 402 (that response is returned to the caller as-is).
|
|
294
|
+
* Use it to authorize follow-up requests (e.g. polling) without re-paying.
|
|
295
|
+
*/
|
|
296
|
+
credentials?: PaymentCredentials;
|
|
297
|
+
}
|
|
298
|
+
/** Apply a previously-obtained credential to the outgoing request headers. */
|
|
299
|
+
declare const applyCredentials: (headers: Headers, credentials: PaymentCredentials) => void;
|
|
300
|
+
/** Attach payment metadata to a response and return it (typed). */
|
|
301
|
+
declare const attachPayment: (response: Response, payment: PaymentInfo | undefined) => PaidResponse;
|
|
302
|
+
/** Payment metadata describing a request authorized with a reused credential. */
|
|
303
|
+
declare const reusedCredentialPayment: (credentials: PaymentCredentials | undefined) => PaymentInfo | undefined;
|
|
304
|
+
/** Satoshi amount of a BOLT11 invoice (0 when it cannot be decoded). */
|
|
305
|
+
declare const getInvoiceAmount: (invoice: string) => number;
|
|
250
306
|
declare function createGuardedWallet(wallet: Wallet, maxAmountSats: number): Wallet;
|
|
251
307
|
|
|
252
|
-
declare const fetch402: (url: string, fetchArgs: RequestInit, options: {
|
|
253
|
-
wallet: Wallet;
|
|
308
|
+
declare const fetch402: (url: string, fetchArgs: RequestInit, options: Fetch402Options & {
|
|
254
309
|
maxAmount?: number;
|
|
255
|
-
}) => Promise<
|
|
310
|
+
}) => Promise<PaidResponse>;
|
|
256
311
|
|
|
257
|
-
declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options:
|
|
258
|
-
wallet: Wallet;
|
|
259
|
-
}) => Promise<Response>;
|
|
312
|
+
declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
260
313
|
|
|
261
314
|
interface WwwAuthenticatePayload {
|
|
262
315
|
token: string;
|
|
@@ -314,9 +367,7 @@ interface X402Requirements {
|
|
|
314
367
|
* the 402 back to the caller.
|
|
315
368
|
*/
|
|
316
369
|
declare const findX402LightningRequirements: (x402Header: string) => X402Requirements | null;
|
|
317
|
-
declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options:
|
|
318
|
-
wallet: Wallet;
|
|
319
|
-
}) => Promise<Response>;
|
|
370
|
+
declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
320
371
|
|
|
321
372
|
/**
|
|
322
373
|
* Fetch a resource protected by the draft-lightning-charge-00 payment
|
|
@@ -327,13 +378,13 @@ declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: {
|
|
|
327
378
|
* the function pays the embedded BOLT11 invoice and retries with the
|
|
328
379
|
* resulting preimage as the credential.
|
|
329
380
|
*
|
|
330
|
-
*
|
|
331
|
-
*
|
|
332
|
-
*
|
|
381
|
+
* Pass a previous credential via `options.credentials` to reuse it (e.g. when
|
|
382
|
+
* polling); the credential is applied and the function NEVER pays again, even
|
|
383
|
+
* if the server still responds with a 402 (that response is returned as-is).
|
|
384
|
+
* Note: lightning-charge typically uses consume-once challenge semantics, so a
|
|
385
|
+
* reused credential is only accepted by servers that explicitly support it.
|
|
333
386
|
*/
|
|
334
|
-
declare const fetchWithMpp: (url: string, fetchArgs: RequestInit, options:
|
|
335
|
-
wallet: Wallet;
|
|
336
|
-
}) => Promise<Response>;
|
|
387
|
+
declare const fetchWithMpp: (url: string, fetchArgs: RequestInit, options: Fetch402Options) => Promise<PaidResponse>;
|
|
337
388
|
|
|
338
389
|
interface FiatCurrency {
|
|
339
390
|
code: string;
|
|
@@ -357,5 +408,49 @@ declare const getFormattedFiatValue: ({ satoshi, currency, locale, }: {
|
|
|
357
408
|
locale: string;
|
|
358
409
|
}) => Promise<string>;
|
|
359
410
|
|
|
360
|
-
|
|
361
|
-
|
|
411
|
+
type Bip21 = {
|
|
412
|
+
/** Bare on-chain bitcoin address (no scheme, no query string). */
|
|
413
|
+
address: string;
|
|
414
|
+
/** Requested amount in BTC, as defined by BIP21 (e.g. 0.01). */
|
|
415
|
+
amount?: number;
|
|
416
|
+
/** Requested amount converted to satoshis, for convenience. */
|
|
417
|
+
amountSats?: number;
|
|
418
|
+
/** Label for the recipient, decoded. */
|
|
419
|
+
label?: string;
|
|
420
|
+
/** Free-form message, decoded. */
|
|
421
|
+
message?: string;
|
|
422
|
+
/** BOLT11 invoice or LNURL, from the `lightning=` parameter (unified QR). */
|
|
423
|
+
lightning?: string;
|
|
424
|
+
/** BOLT12 offer, from the `lno=` parameter. */
|
|
425
|
+
lno?: string;
|
|
426
|
+
/**
|
|
427
|
+
* `req-*` parameters that the client doesn't know how to handle.
|
|
428
|
+
* Per BIP21, callers MUST reject the URI if this is non-empty.
|
|
429
|
+
*/
|
|
430
|
+
unknownRequiredParams: string[];
|
|
431
|
+
/** All query parameters, decoded, for advanced/custom use. */
|
|
432
|
+
params: Record<string, string>;
|
|
433
|
+
};
|
|
434
|
+
|
|
435
|
+
/**
|
|
436
|
+
* Parse a BIP21 (`bitcoin:`) URI. Returns `null` if the input doesn't have the
|
|
437
|
+
* `bitcoin:` scheme.
|
|
438
|
+
*
|
|
439
|
+
* The address is returned as-is (case preserved) — callers should validate it
|
|
440
|
+
* separately if they need to ensure it's a well-formed bitcoin address.
|
|
441
|
+
*
|
|
442
|
+
* Per BIP21, parameters prefixed with `req-` are required: if the client
|
|
443
|
+
* doesn't understand any of them, the payment MUST NOT be made. The unknown
|
|
444
|
+
* required params are surfaced via `unknownRequiredParams` so callers can
|
|
445
|
+
* decide how to fail.
|
|
446
|
+
*
|
|
447
|
+
* @example
|
|
448
|
+
* parseBip21("bitcoin:bc1q...?amount=0.001&lightning=lnbc...")
|
|
449
|
+
* // => { address: "bc1q...", amount: 0.001, amountSats: 100000, lightning: "lnbc...", ... }
|
|
450
|
+
*/
|
|
451
|
+
declare const parseBip21: (uri: string) => Bip21 | null;
|
|
452
|
+
/** Returns true if the input starts with the `bitcoin:` URI scheme. */
|
|
453
|
+
declare const isBip21: (uri: string) => boolean;
|
|
454
|
+
|
|
455
|
+
export { DEFAULT_PROXY, Invoice, LN_ADDRESS_REGEX, LightningAddress, applyCredentials, attachPayment, createGuardedWallet, decodeInvoice, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, findX402LightningRequirements, fromHexString, generateZapEvent, getEventHash, getFiatBtcRate, getFiatCurrencies, getFiatValue, getFormattedFiatValue, getInvoiceAmount, getSatoshiValue, isBip21, isUrl, isValidAmount, issueL402Macaroon, makeL402AuthenticateHeader, parseBip21, parseKeysendResponse, parseL402, parseL402Authorization, parseLnUrlPayResponse, parseNostrResponse, reusedCredentialPayment, sendBoostagram, serializeEvent, validateEvent, validatePreimage, verifyL402Macaroon };
|
|
456
|
+
export type { Bip21, Boost, BoostArguments, BoostOptions, Event, Fetch402Options, FiatCurrency, InvoiceArgs, KeySendRawData, KeysendResponse, LUD18PayerData, LUD18ServicePayerData, LnUrlPayResponse, LnUrlRawData, MacaroonPayload, NostrProvider, NostrResponse, PaidResponse, PaymentCredentials, PaymentInfo, RequestInvoiceArgs, SuccessAction, Wallet, WeblnBoostParams, ZapArgs, ZapOptions };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@getalby/lightning-tools",
|
|
3
|
-
"version": "8.
|
|
3
|
+
"version": "8.2.0",
|
|
4
4
|
"description": "Collection of helpful building blocks and tools to develop Bitcoin Lightning web apps",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": "https://github.com/getAlby/js-lightning-tools.git",
|
|
@@ -68,6 +68,11 @@
|
|
|
68
68
|
"import": "./dist/esm/podcasting2.js",
|
|
69
69
|
"require": "./dist/cjs/podcasting2.cjs",
|
|
70
70
|
"types": "./dist/types/podcasting2.d.ts"
|
|
71
|
+
},
|
|
72
|
+
"./bip21": {
|
|
73
|
+
"import": "./dist/esm/bip21.js",
|
|
74
|
+
"require": "./dist/cjs/bip21.cjs",
|
|
75
|
+
"types": "./dist/types/bip21.d.ts"
|
|
71
76
|
}
|
|
72
77
|
},
|
|
73
78
|
"scripts": {
|