@integraledger/terms 0.1.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.
Files changed (171) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +539 -0
  3. package/dist/agreement.d.ts +23 -0
  4. package/dist/agreement.js +264 -0
  5. package/dist/channels.d.ts +49 -0
  6. package/dist/channels.js +395 -0
  7. package/dist/gate.d.ts +69 -0
  8. package/dist/gate.js +347 -0
  9. package/dist/index.d.ts +5 -0
  10. package/dist/index.js +4 -0
  11. package/dist/pairings/ack-payment-request.d.ts +1 -0
  12. package/dist/pairings/ack-payment-request.js +12 -0
  13. package/dist/pairings/acp-checkout-delegated.d.ts +2 -0
  14. package/dist/pairings/acp-checkout-delegated.js +28 -0
  15. package/dist/pairings/acp-checkout-undelegated.d.ts +1 -0
  16. package/dist/pairings/acp-checkout-undelegated.js +11 -0
  17. package/dist/pairings/ap2-checkout-mandate.d.ts +2 -0
  18. package/dist/pairings/ap2-checkout-mandate.js +23 -0
  19. package/dist/pairings/batch.d.ts +29 -0
  20. package/dist/pairings/batch.js +83 -0
  21. package/dist/pairings/card-mastercard-vi-autonomous.d.ts +1 -0
  22. package/dist/pairings/card-mastercard-vi-autonomous.js +3 -0
  23. package/dist/pairings/card-mastercard-vi-immediate.d.ts +1 -0
  24. package/dist/pairings/card-mastercard-vi-immediate.js +3 -0
  25. package/dist/pairings/card-seller-reference.d.ts +1 -0
  26. package/dist/pairings/card-seller-reference.js +3 -0
  27. package/dist/pairings/card-visa-tap.d.ts +1 -0
  28. package/dist/pairings/card-visa-tap.js +3 -0
  29. package/dist/pairings/card.d.ts +7 -0
  30. package/dist/pairings/card.js +68 -0
  31. package/dist/pairings/common.d.ts +54 -0
  32. package/dist/pairings/common.js +134 -0
  33. package/dist/pairings/evm-x402.d.ts +3 -0
  34. package/dist/pairings/evm-x402.js +49 -0
  35. package/dist/pairings/index.d.ts +3 -0
  36. package/dist/pairings/index.js +134 -0
  37. package/dist/pairings/lightning.d.ts +17 -0
  38. package/dist/pairings/lightning.js +112 -0
  39. package/dist/pairings/lnbtc-request.d.ts +24 -0
  40. package/dist/pairings/lnbtc-request.js +175 -0
  41. package/dist/pairings/mpp-charge-card.d.ts +1 -0
  42. package/dist/pairings/mpp-charge-card.js +3 -0
  43. package/dist/pairings/mpp-charge-evm-authorization.d.ts +1 -0
  44. package/dist/pairings/mpp-charge-evm-authorization.js +3 -0
  45. package/dist/pairings/mpp-charge-evm-hash.d.ts +1 -0
  46. package/dist/pairings/mpp-charge-evm-hash.js +3 -0
  47. package/dist/pairings/mpp-charge-evm-permit2.d.ts +1 -0
  48. package/dist/pairings/mpp-charge-evm-permit2.js +3 -0
  49. package/dist/pairings/mpp-charge-evm-transaction.d.ts +1 -0
  50. package/dist/pairings/mpp-charge-evm-transaction.js +3 -0
  51. package/dist/pairings/mpp-charge-hedera.d.ts +23 -0
  52. package/dist/pairings/mpp-charge-hedera.js +137 -0
  53. package/dist/pairings/mpp-charge-nearintents.d.ts +2 -0
  54. package/dist/pairings/mpp-charge-nearintents.js +19 -0
  55. package/dist/pairings/mpp-charge-solana.d.ts +1 -0
  56. package/dist/pairings/mpp-charge-solana.js +25 -0
  57. package/dist/pairings/mpp-charge-stellar.d.ts +1 -0
  58. package/dist/pairings/mpp-charge-stellar.js +16 -0
  59. package/dist/pairings/mpp-charge-stripe.d.ts +1 -0
  60. package/dist/pairings/mpp-charge-stripe.js +3 -0
  61. package/dist/pairings/mpp-charge-tempo-memo.d.ts +9 -0
  62. package/dist/pairings/mpp-charge-tempo-memo.js +10 -0
  63. package/dist/pairings/mpp-charge-tempo-push.d.ts +12 -0
  64. package/dist/pairings/mpp-charge-tempo-push.js +21 -0
  65. package/dist/pairings/mpp-charge-usdc-evm.d.ts +1 -0
  66. package/dist/pairings/mpp-charge-usdc-evm.js +6 -0
  67. package/dist/pairings/mpp-charge-usdc-gateway.d.ts +2 -0
  68. package/dist/pairings/mpp-charge-usdc-gateway.js +33 -0
  69. package/dist/pairings/mpp-charge-usdc-solana.d.ts +1 -0
  70. package/dist/pairings/mpp-charge-usdc-solana.js +25 -0
  71. package/dist/pairings/mpp-charge-usdc-stacks.d.ts +1 -0
  72. package/dist/pairings/mpp-charge-usdc-stacks.js +17 -0
  73. package/dist/pairings/mpp-charge-xrpl.d.ts +1 -0
  74. package/dist/pairings/mpp-charge-xrpl.js +20 -0
  75. package/dist/pairings/mpp-confirm-only.d.ts +2 -0
  76. package/dist/pairings/mpp-confirm-only.js +21 -0
  77. package/dist/pairings/mpp-rails.d.ts +48 -0
  78. package/dist/pairings/mpp-rails.js +71 -0
  79. package/dist/pairings/mpp-session-evm.d.ts +1 -0
  80. package/dist/pairings/mpp-session-evm.js +3 -0
  81. package/dist/pairings/mpp-session-hedera.d.ts +2 -0
  82. package/dist/pairings/mpp-session-hedera.js +41 -0
  83. package/dist/pairings/mpp-session-solana.d.ts +1 -0
  84. package/dist/pairings/mpp-session-solana.js +60 -0
  85. package/dist/pairings/mpp-session-tempo.d.ts +1 -0
  86. package/dist/pairings/mpp-session-tempo.js +3 -0
  87. package/dist/pairings/mpp-session-xrpl.d.ts +1 -0
  88. package/dist/pairings/mpp-session-xrpl.js +42 -0
  89. package/dist/pairings/mpp-session.d.ts +5 -0
  90. package/dist/pairings/mpp-session.js +65 -0
  91. package/dist/pairings/mpp-subscription-stripe.d.ts +1 -0
  92. package/dist/pairings/mpp-subscription-stripe.js +6 -0
  93. package/dist/pairings/mpp-subscription-tempo.d.ts +2 -0
  94. package/dist/pairings/mpp-subscription-tempo.js +2 -0
  95. package/dist/pairings/mpp.d.ts +43 -0
  96. package/dist/pairings/mpp.js +194 -0
  97. package/dist/pairings/protocol-groups.d.ts +17 -0
  98. package/dist/pairings/protocol-groups.js +27 -0
  99. package/dist/pairings/ucp-booking-ap2-mandate.d.ts +1 -0
  100. package/dist/pairings/ucp-booking-ap2-mandate.js +3 -0
  101. package/dist/pairings/ucp-booking-unsigned.d.ts +1 -0
  102. package/dist/pairings/ucp-booking-unsigned.js +3 -0
  103. package/dist/pairings/ucp-checkout-ap2-mandate.d.ts +1 -0
  104. package/dist/pairings/ucp-checkout-ap2-mandate.js +3 -0
  105. package/dist/pairings/ucp-checkout-unsigned.d.ts +1 -0
  106. package/dist/pairings/ucp-checkout-unsigned.js +3 -0
  107. package/dist/pairings/ucp.d.ts +5 -0
  108. package/dist/pairings/ucp.js +35 -0
  109. package/dist/pairings/x402-account-rails.d.ts +25 -0
  110. package/dist/pairings/x402-account-rails.js +52 -0
  111. package/dist/pairings/x402-auth-capture-eip155-eip3009.d.ts +1 -0
  112. package/dist/pairings/x402-auth-capture-eip155-eip3009.js +3 -0
  113. package/dist/pairings/x402-auth-capture-eip155-permit2.d.ts +1 -0
  114. package/dist/pairings/x402-auth-capture-eip155-permit2.js +3 -0
  115. package/dist/pairings/x402-batch-settlement-cloudflare.d.ts +2 -0
  116. package/dist/pairings/x402-batch-settlement-cloudflare.js +21 -0
  117. package/dist/pairings/x402-batch-settlement-eip155.d.ts +2 -0
  118. package/dist/pairings/x402-batch-settlement-eip155.js +32 -0
  119. package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
  120. package/dist/pairings/x402-batch-settlement-solana.js +55 -0
  121. package/dist/pairings/x402-exact-algorand.d.ts +1 -0
  122. package/dist/pairings/x402-exact-algorand.js +37 -0
  123. package/dist/pairings/x402-exact-aptos.d.ts +1 -0
  124. package/dist/pairings/x402-exact-aptos.js +9 -0
  125. package/dist/pairings/x402-exact-cardano.d.ts +1 -0
  126. package/dist/pairings/x402-exact-cardano.js +7 -0
  127. package/dist/pairings/x402-exact-casper.d.ts +2 -0
  128. package/dist/pairings/x402-exact-casper.js +21 -0
  129. package/dist/pairings/x402-exact-ccd.d.ts +2 -0
  130. package/dist/pairings/x402-exact-ccd.js +20 -0
  131. package/dist/pairings/x402-exact-eip155-eip3009.d.ts +1 -0
  132. package/dist/pairings/x402-exact-eip155-eip3009.js +3 -0
  133. package/dist/pairings/x402-exact-eip155-erc7710-salt.d.ts +1 -0
  134. package/dist/pairings/x402-exact-eip155-erc7710-salt.js +3 -0
  135. package/dist/pairings/x402-exact-eip155-erc7710.d.ts +1 -0
  136. package/dist/pairings/x402-exact-eip155-erc7710.js +3 -0
  137. package/dist/pairings/x402-exact-eip155-permit2.d.ts +1 -0
  138. package/dist/pairings/x402-exact-eip155-permit2.js +3 -0
  139. package/dist/pairings/x402-exact-hedera-transfer-executor.d.ts +1 -0
  140. package/dist/pairings/x402-exact-hedera-transfer-executor.js +23 -0
  141. package/dist/pairings/x402-exact-hedera.d.ts +3 -0
  142. package/dist/pairings/x402-exact-hedera.js +46 -0
  143. package/dist/pairings/x402-exact-near.d.ts +2 -0
  144. package/dist/pairings/x402-exact-near.js +34 -0
  145. package/dist/pairings/x402-exact-polkadot-lcp-assets-remark.d.ts +2 -0
  146. package/dist/pairings/x402-exact-polkadot-lcp-assets-remark.js +20 -0
  147. package/dist/pairings/x402-exact-solana.d.ts +11 -0
  148. package/dist/pairings/x402-exact-solana.js +36 -0
  149. package/dist/pairings/x402-exact-starknet.d.ts +2 -0
  150. package/dist/pairings/x402-exact-starknet.js +20 -0
  151. package/dist/pairings/x402-exact-stellar.d.ts +1 -0
  152. package/dist/pairings/x402-exact-stellar.js +17 -0
  153. package/dist/pairings/x402-exact-sui.d.ts +1 -0
  154. package/dist/pairings/x402-exact-sui.js +10 -0
  155. package/dist/pairings/x402-exact-tron-lcp-trc20-memo.d.ts +2 -0
  156. package/dist/pairings/x402-exact-tron-lcp-trc20-memo.js +45 -0
  157. package/dist/pairings/x402-exact-tvm.d.ts +2 -0
  158. package/dist/pairings/x402-exact-tvm.js +35 -0
  159. package/dist/pairings/x402-exact-xrpl.d.ts +1 -0
  160. package/dist/pairings/x402-exact-xrpl.js +27 -0
  161. package/dist/pairings/x402-rail.d.ts +31 -0
  162. package/dist/pairings/x402-rail.js +65 -0
  163. package/dist/pairings/x402-upto-eip155-permit2.d.ts +1 -0
  164. package/dist/pairings/x402-upto-eip155-permit2.js +3 -0
  165. package/dist/pairings/x402-upto-solana.d.ts +1 -0
  166. package/dist/pairings/x402-upto-solana.js +42 -0
  167. package/dist/transact.d.ts +20 -0
  168. package/dist/transact.js +53 -0
  169. package/dist/types.d.ts +169 -0
  170. package/dist/types.js +2 -0
  171. package/package.json +64 -0
@@ -0,0 +1,264 @@
1
+ /**
2
+ * The agreement payment. `agree` asks the agreement URL for its challenge, pays it through the buyer piece of the
3
+ * pairing that placed it, a pairing whose payment is itself a public proof of the ATR hash, and returns the resource's
4
+ * receipt once the payment is recorded. Nothing is signed when the challenge advertises another hash, and nothing is
5
+ * sent unless what was signed carries the hash. Once sent, the same signed payment is sent again after each 202, 5xx or
6
+ * timeout, each paid request bounded by min(`maxTimeoutSeconds`, 120) + 60 + 10 seconds and the whole exchange by the
7
+ * agreement option's `maxTimeoutSeconds` + 180 seconds; no second agreement payment is signed, and every decline after
8
+ * it was sent carries it as `moved`.
9
+ */
10
+ import { BINDINGS, hashEquals, isHttpsLink, isOtherSchemeLink, pairingOf, parseJson } from "@integraledger/lcp";
11
+ import { pay, redirected } from "./gate.js";
12
+ const UNPAID_DEADLINE_MS = 10_000;
13
+ const EXCHANGE_CAP_S = 120;
14
+ const SETTLE_S = 60;
15
+ const VERIFY_S = 10;
16
+ const WINDOW_EXTRA_S = 180;
17
+ const MAX_ANSWER_BYTES = 65_536;
18
+ const RETRY_DEFAULT_S = 2;
19
+ const RETRY_MIN_S = 1;
20
+ const DECIMAL = /^[0-9]{1,9}$/;
21
+ function declined(code, detail) {
22
+ return { decline: { code, detail } };
23
+ }
24
+ const failed = (detail) => declined("agreement-failed", detail);
25
+ function isRefusal(v) {
26
+ return typeof v === "object" && v !== null && v.refused === true;
27
+ }
28
+ function isObject(v) {
29
+ return typeof v === "object" && v !== null && !Array.isArray(v);
30
+ }
31
+ /** Standard base64 of the UTF-8 bytes of `text`. */
32
+ function toBase64(text) {
33
+ const bytes = new TextEncoder().encode(text);
34
+ let binary = "";
35
+ for (const b of bytes)
36
+ binary += String.fromCharCode(b);
37
+ return btoa(binary);
38
+ }
39
+ /** The JSON value a base64 header carries, or undefined when it is not base64 of UTF-8 JSON. */
40
+ function fromBase64Json(header) {
41
+ if (header.length > MAX_ANSWER_BYTES)
42
+ return undefined;
43
+ try {
44
+ const binary = atob(header);
45
+ const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
46
+ return parseJson(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
47
+ }
48
+ catch {
49
+ return undefined;
50
+ }
51
+ }
52
+ /** `retry-after` in whole seconds, at least 1; 2 when absent or not a number of seconds. */
53
+ function retrySeconds(header) {
54
+ const v = header?.trim();
55
+ if (v === undefined || !DECIMAL.test(v))
56
+ return RETRY_DEFAULT_S;
57
+ return Math.max(RETRY_MIN_S, Number(v));
58
+ }
59
+ /** A 5xx answer to the paid request, which is read as a timeout: the same payment is sent again. */
60
+ function isServerError(status) {
61
+ return status >= 500 && status <= 599;
62
+ }
63
+ function sleep(ms) {
64
+ return new Promise((resolve) => setTimeout(resolve, ms));
65
+ }
66
+ /**
67
+ * One GET of the agreement URL, with no redirect followed and a deadline of `ms` over headers and body. A redirect is
68
+ * `agreement-failed`. A 200 body is read up to 64 KiB; any other body is cancelled unread.
69
+ */
70
+ async function get(fetch, url, signature, ms) {
71
+ const controller = new AbortController();
72
+ const timer = setTimeout(() => controller.abort(new DOMException("The agreement request passed its deadline.", "TimeoutError")), ms);
73
+ const deadline = new Promise((_, reject) => {
74
+ controller.signal.addEventListener("abort", () => reject(controller.signal.reason), { once: true });
75
+ });
76
+ deadline.catch(() => undefined);
77
+ let body = null;
78
+ let reader;
79
+ let whole = false;
80
+ try {
81
+ const init = { method: "GET", redirect: "manual", signal: controller.signal };
82
+ if (signature !== undefined)
83
+ init.headers = { "PAYMENT-SIGNATURE": signature };
84
+ const response = await Promise.race([fetch(url, init), deadline]);
85
+ body = response.body;
86
+ if (redirected(response))
87
+ return failed("The agreement URL answered with a redirect.");
88
+ const answer = {
89
+ status: response.status,
90
+ paymentRequired: response.headers.get("payment-required"),
91
+ retryAfter: response.headers.get("retry-after"),
92
+ body: null,
93
+ };
94
+ if (response.status !== 200)
95
+ return answer;
96
+ const declared = response.headers.get("content-length")?.trim();
97
+ if (declared !== undefined && /^[0-9]+$/.test(declared) && Number(declared) > MAX_ANSWER_BYTES) {
98
+ return failed("The agreement receipt is larger than 64 KiB.");
99
+ }
100
+ if (body === null) {
101
+ whole = true;
102
+ return { ...answer, body: new Uint8Array(0) };
103
+ }
104
+ reader = body.getReader();
105
+ const chunks = [];
106
+ let total = 0;
107
+ for (;;) {
108
+ const next = await Promise.race([reader.read(), deadline]);
109
+ if (next.done)
110
+ break;
111
+ if (!(next.value instanceof Uint8Array))
112
+ return failed("The agreement URL served a non-byte chunk.");
113
+ total += next.value.length;
114
+ if (total > MAX_ANSWER_BYTES)
115
+ return failed("The agreement receipt is larger than 64 KiB.");
116
+ chunks.push(next.value);
117
+ }
118
+ whole = true;
119
+ const bytes = new Uint8Array(total);
120
+ let at = 0;
121
+ for (const c of chunks) {
122
+ bytes.set(c, at);
123
+ at += c.length;
124
+ }
125
+ return { ...answer, body: bytes };
126
+ }
127
+ catch {
128
+ return { unanswered: true };
129
+ }
130
+ finally {
131
+ clearTimeout(timer);
132
+ if (!whole) {
133
+ cancel(reader ?? body);
134
+ controller.abort();
135
+ }
136
+ }
137
+ }
138
+ /** Cancels a body or its reader, ignoring whatever the cancellation answers. */
139
+ function cancel(s) {
140
+ if (s === null || s === undefined)
141
+ return;
142
+ try {
143
+ s.cancel().catch(() => undefined);
144
+ }
145
+ catch {
146
+ // A body that cannot be cancelled is left to the fetch's own abort.
147
+ }
148
+ }
149
+ /** The receipt a 200 carries, when it is the agreement receipt for `h`. */
150
+ function receiptOf(body, h) {
151
+ let parsed;
152
+ try {
153
+ parsed = parseJson(new TextDecoder("utf-8", { fatal: true }).decode(body ?? new Uint8Array(0)));
154
+ }
155
+ catch {
156
+ return failed("The agreement URL answered 200 without a JSON receipt.");
157
+ }
158
+ if (!isObject(parsed))
159
+ return failed("The agreement URL answered 200 without a JSON receipt.");
160
+ const { atrHash, agreed, network, transaction } = parsed;
161
+ if (typeof atrHash !== "string" || !hashEquals(atrHash, h)) {
162
+ return failed("The agreement receipt names another ATR hash.");
163
+ }
164
+ if (agreed !== true || typeof network !== "string" || typeof transaction !== "string") {
165
+ return failed("The agreement receipt is not a recorded agreement.");
166
+ }
167
+ return { receipt: { atrHash: atrHash, agreed, network, transaction } };
168
+ }
169
+ function isPublicProof(binding) {
170
+ const pattern = binding.pattern;
171
+ return isObject(pattern) && pattern["publicProof"] === true;
172
+ }
173
+ /** The pairing that placed the agreement option, when its payment is itself a public proof, with that option. */
174
+ function agreementPairing(required) {
175
+ const accepts = isObject(required) ? required["accepts"] : undefined;
176
+ if (!Array.isArray(accepts) || accepts.length === 0 || !isObject(accepts[0])) {
177
+ return declined("offer-unreadable", "x402/no-payable-option");
178
+ }
179
+ const option = accepts[0];
180
+ const id = pairingOf(option);
181
+ const binding = id === undefined ? undefined : BINDINGS.find((b) => b.id === id);
182
+ if (binding === undefined)
183
+ return declined("pairing-not-supported", "The agreement option names no pairing the gate serves.");
184
+ if (!isPublicProof(binding)) {
185
+ return declined("pairing-not-supported", `The agreement pairing ${String(id)} is not itself a public proof.`);
186
+ }
187
+ return { binding, option };
188
+ }
189
+ /** The paid request's deadline and the whole exchange's, in seconds, from the agreement option's `maxTimeoutSeconds`. */
190
+ function bounds(option) {
191
+ const t = option.maxTimeoutSeconds;
192
+ if (typeof t !== "number" || !Number.isSafeInteger(t) || t <= 0)
193
+ return undefined;
194
+ return { request: Math.min(t, EXCHANGE_CAP_S) + SETTLE_S + VERIFY_S, exchange: t + WINDOW_EXTRA_S };
195
+ }
196
+ /**
197
+ * Pays the agreement for `h` at `url` with `signer`, and returns the receipt. `bytes` are the ATR the gate compared,
198
+ * for a pairing whose build reads them; `inputs` are the buyer's own chain values; `ns` is the namespace of the pairing
199
+ * whose offer named the URL, which a refused URL's detail carries with the protocol package's code.
200
+ */
201
+ export async function agree(h, url, signer, fetch, held) {
202
+ if (!isHttpsLink(url)) {
203
+ const fault = isOtherSchemeLink(url) ? "link-not-https" : "legal-context-malformed";
204
+ return declined("link-not-https", held.ns === undefined ? "The agreement URL is not an https URL." : `${held.ns}/${fault}`);
205
+ }
206
+ const { bytes } = held;
207
+ const inputs = held.inputs ?? {};
208
+ const unpaid = await get(fetch, url, undefined, UNPAID_DEADLINE_MS);
209
+ if ("decline" in unpaid)
210
+ return unpaid;
211
+ if ("unanswered" in unpaid)
212
+ return failed("The agreement URL could not be reached.");
213
+ if (unpaid.status === 200)
214
+ return receiptOf(unpaid.body, h);
215
+ if (unpaid.status === 202) {
216
+ return declined("agreement-pending", "An agreement payment for this ATR is already settling.");
217
+ }
218
+ if (unpaid.status !== 402)
219
+ return failed(`The agreement URL answered status ${unpaid.status}.`);
220
+ const required = unpaid.paymentRequired === null ? undefined : fromBase64Json(unpaid.paymentRequired);
221
+ if (required === undefined)
222
+ return failed("The agreement URL answered 402 without a readable PAYMENT-REQUIRED.");
223
+ const found = agreementPairing(required);
224
+ if ("decline" in found)
225
+ return found;
226
+ const limits = bounds(found.option);
227
+ if (limits === undefined)
228
+ return declined("offer-unreadable", "x402/option-malformed");
229
+ const read = found.binding.read(required);
230
+ if (isRefusal(read))
231
+ return declined("offer-unreadable", read.code);
232
+ if (!hashEquals(read.h, h)) {
233
+ return declined("hash-mismatch", "The agreement challenge advertises another ATR hash.");
234
+ }
235
+ const paid = await pay(found.binding, read, required, signer, inputs, bytes);
236
+ if ("decline" in paid)
237
+ return paid;
238
+ if (paid.signed === null)
239
+ return declined("offer-unreadable", "The agreement payment gave nothing to sign.");
240
+ const signed = paid.signed;
241
+ const payment = toBase64(JSON.stringify(signed));
242
+ const moved = { signed, bytes, h };
243
+ const keep = (d) => ({ ...d, moved });
244
+ const end = Date.now() + limits.exchange * 1000;
245
+ for (;;) {
246
+ const remaining = end - Date.now();
247
+ if (remaining <= 0)
248
+ return keep(declined("agreement-pending", "The agreement payment was sent and is not yet recorded."));
249
+ const answer = await get(fetch, url, payment, Math.min(limits.request * 1000, remaining));
250
+ if ("decline" in answer)
251
+ return keep(answer);
252
+ let wait = RETRY_DEFAULT_S * 1000;
253
+ if (!("unanswered" in answer) && !isServerError(answer.status)) {
254
+ if (answer.status === 200) {
255
+ const r = receiptOf(answer.body, h);
256
+ return "decline" in r ? keep(r) : r;
257
+ }
258
+ if (answer.status !== 202)
259
+ return keep(failed(`The agreement URL answered status ${answer.status} to the payment.`));
260
+ wait = retrySeconds(answer.retryAfter) * 1000;
261
+ }
262
+ await sleep(Math.max(0, Math.min(wait, end - Date.now())));
263
+ }
264
+ }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The buyer's channel steps. One ATR covers a whole channel: the gate compares it once, at the opening, and the caller
3
+ * keeps the result as a `ChannelHold`, the ATR's bytes together with the signed opening and the channel it names.
4
+ * `within` signs a later voucher only for a channel held this way, re-deriving everything from the hold and never from
5
+ * the new challenge, and only when that challenge advertises the held ATR's hash. It serves x402's batch channels and
6
+ * MPP's sessions through the binding's `buildWithin`. `recordCharge` records the server's cumulative charge, bounded by
7
+ * what was signed.
8
+ */
9
+ import { type AtrHash, type Json } from "@integraledger/lcp";
10
+ import { type Binding, type Declined, type Inputs, type Presented, type Signer } from "./types.js";
11
+ /** A channel the buyer opened for an ATR it compared, as JSON the caller keeps and hands back. */
12
+ export interface ChannelHold {
13
+ pairing: string;
14
+ network: string;
15
+ channel: string;
16
+ h: AtrHash;
17
+ /** Base64 of the ATR bytes the opening compared. */
18
+ atr: string;
19
+ /** The signed opening payment, exactly as the gate returned it. */
20
+ opening: Json;
21
+ /** The server's cumulative charge last recorded, decimal; "0" at the opening. */
22
+ charged: string;
23
+ /** The largest `maxClaimableAmount` signed in this channel, decimal. */
24
+ signedMax: string;
25
+ }
26
+ /**
27
+ * Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt
28
+ * `transact` returned beside the opening, where it returned one. The opening, with that receipt, must be of kind `open`,
29
+ * carry the hash of these bytes, and name its channel; the hold keeps all three together.
30
+ */
31
+ export declare function openChannel(bytes: Uint8Array, opened: Presented, binding: Binding, landed?: unknown): Promise<ChannelHold | Declined>;
32
+ /**
33
+ * Signs one later voucher, or a refund, in a held channel. The ATR bytes, the opening's hash and the opening's
34
+ * channel are re-derived from the hold, and the challenge must advertise the held hash. A voucher's
35
+ * `maxClaimableAmount` is the recorded charge plus the option's amount; a refund's is the recorded charge. `inputs`
36
+ * are the buyer's own chain values a refund's build takes. What was signed must be of the expected kind and belong to
37
+ * the held channel, or it is dropped.
38
+ */
39
+ export declare function within(doc: unknown, hold: ChannelHold, binding: Binding, signer: Signer, refund?: {
40
+ amount?: string;
41
+ }, inputs?: Inputs): Promise<{
42
+ signed: Presented;
43
+ hold: ChannelHold;
44
+ } | Declined>;
45
+ /**
46
+ * Records the server's cumulative charge for the channel. It must be a decimal no lower than the charge last recorded
47
+ * and no higher than the largest amount signed in the channel.
48
+ */
49
+ export declare function recordCharge(hold: ChannelHold, chargedCumulativeAmount: string): ChannelHold | Declined;