@tuwaio/nova-payments 0.0.0 → 0.0.1

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 (45) hide show
  1. package/README.md +133 -11
  2. package/dist/OwnConnection-ET76SUMX.js +1 -0
  3. package/dist/OwnConnection-S5SQLIBT.cjs +1 -0
  4. package/dist/chunk-PUMIYLSN.js +1 -0
  5. package/dist/chunk-S3L4QDPT.cjs +1 -0
  6. package/dist/chunk-WOAPFVQF.js +1 -0
  7. package/dist/chunk-XOVRZTAM.cjs +1 -0
  8. package/dist/de-53SSE6O2.js +1 -0
  9. package/dist/de-LB5XSRMX.cjs +1 -0
  10. package/dist/es-LP3HJ4KB.js +1 -0
  11. package/dist/es-VDW2RZMP.cjs +1 -0
  12. package/dist/evm/index.cjs +1 -1
  13. package/dist/evm/index.d.cts +3 -3
  14. package/dist/evm/index.d.ts +3 -3
  15. package/dist/evm/index.js +1 -1
  16. package/dist/i18n/index.cjs +1 -1
  17. package/dist/i18n/index.d.cts +4 -23
  18. package/dist/i18n/index.d.ts +4 -23
  19. package/dist/i18n/index.js +1 -1
  20. package/dist/index.cjs +2 -1
  21. package/dist/index.css +457 -43
  22. package/dist/index.d.cts +1924 -242
  23. package/dist/index.d.ts +1924 -242
  24. package/dist/index.js +2 -1
  25. package/dist/it-6IQFXLAR.cjs +1 -0
  26. package/dist/it-JJ5Z5EUF.js +1 -0
  27. package/dist/locales-DzMinYsr.d.cts +1221 -0
  28. package/dist/locales-DzMinYsr.d.ts +1221 -0
  29. package/dist/solana/index.cjs +1 -1
  30. package/dist/solana/index.d.cts +7 -4
  31. package/dist/solana/index.d.ts +7 -4
  32. package/dist/solana/index.js +1 -1
  33. package/dist/{types-Bmj8ctqc.d.cts → types-Bp6JUt56.d.cts} +116 -7
  34. package/dist/{types-Bmj8ctqc.d.ts → types-Bp6JUt56.d.ts} +116 -7
  35. package/dist/uk-EI4N5BMM.js +1 -0
  36. package/dist/uk-FVCYLYSB.cjs +1 -0
  37. package/dist/zhCN-BZBMKUUA.js +1 -0
  38. package/dist/zhCN-TA7WU5XS.cjs +1 -0
  39. package/package.json +37 -36
  40. package/dist/chunk-2GRM2VF3.cjs +0 -1
  41. package/dist/chunk-4TPU7WSP.cjs +0 -1
  42. package/dist/chunk-BK3GAYTJ.js +0 -1
  43. package/dist/chunk-XAUJNVKC.js +0 -1
  44. package/dist/locales-DtReb4Tp.d.cts +0 -588
  45. package/dist/locales-DtReb4Tp.d.ts +0 -588
package/dist/index.d.ts CHANGED
@@ -1,19 +1,32 @@
1
- import { P as PaymentsAdapter, C as CheckoutWallet, a as PaymentFamily } from './types-Bmj8ctqc.js';
2
- export { N as NativeFee, b as PulsarTransactionParams, c as canPayWithQr, d as connectedWallet, m as methodFamily, e as methodToken, n as networkName, p as payerFor, f as priceAdjustment, w as walletLabel } from './types-Bmj8ctqc.js';
1
+ import { P as PaymentsAdapter, a as PaymentFamily, C as CheckoutWallet, N as NativeFee } from './types-Bp6JUt56.js';
2
+ export { b as PulsarTransactionParams, c as canPayWithQr, d as connectedWallet, f as familyOf, i as isWalletIconUrl, m as methodFamily, e as methodToken, n as networkName, p as payerFor, g as priceAdjustment, w as walletLabel } from './types-Bp6JUt56.js';
3
3
  import * as react from 'react';
4
- import { ReactNode } from 'react';
5
- import { CheckoutMethod, CheckoutPhase, CheckoutView, CheckoutQuote, PaymentInstructions, CheckoutError, CheckoutStore, CheckoutState, CheckoutApi, EventSourceConstructor, AutoChargeOffer, CheckoutMerchant } from '@tuwaio/quasar-sdk/checkout';
6
- import { N as NovaPaymentsLabels, a as CheckoutLocale, b as NovaPaymentsLabelOverrides } from './locales-DtReb4Tp.js';
4
+ import { ReactNode, ComponentType, ButtonHTMLAttributes, Context } from 'react';
5
+ import { CheckoutMethod, CheckoutView, CheckoutPhase, CheckoutQuote, CheckoutError, CheckoutState, PaymentInstructions, CheckoutApi, EventSourceConstructor, CheckoutStore, RefundPhase, RefundState, RefundStore, PayerProofMessage, AutoChargeOffer, CheckoutMerchant } from '@tuwaio/quasar-sdk/checkout';
6
+ import { NovaPaymentsLabels, CheckoutLocale, NovaPaymentsLabelOverrides } from './i18n/index.js';
7
7
  import { Transaction } from '@tuwaio/pulsar-core';
8
- import { Buyer } from '@tuwaio/quasar-sdk';
8
+ import { StatusTone, StatusEdgeProps } from '@tuwaio/nova-core';
9
+ import { TxStatusVisualProps, TxProgressIndicatorProps, HashLinkProps } from '@tuwaio/nova-transactions';
10
+ import { RefundPreview, Buyer } from '@tuwaio/quasar-sdk';
11
+ import { NovaConnectProviderPropsWithCustomization } from '@tuwaio/nova-connect';
12
+ import { SatelliteConnectProviderProps } from '@tuwaio/satellite-react';
13
+ export { shortAddress } from '@tuwaio/orbit-core';
9
14
 
10
15
  /**
11
16
  * The automatic payments offer of a subscription, after a paid period: the limit the seller may take each period, the
12
- * period, the paying wallet and the account that takes the charges, until when, and how to turn it off. "Allow" asks
13
- * the wallet for the ERC-7715 permission and hands it to Quasar (then the paid outcome says automatic payments are
14
- * on); "Not now" keeps paying each invoice.
17
+ * period, the paying wallet and the seller's wallet the charges are paid to, until when, that Quasar sends each charge
18
+ * for the seller, and how to turn it off. "Allow" takes the wallet through what it needs: to the network of the
19
+ * permission, from a plain account to its smart account (see `smartAccountStatus`: the offer says so first, and MetaMask
20
+ * asks only then), then the ERC-7715 permission, which Quasar takes (the paid outcome then says automatic payments are
21
+ * on); "Not now" keeps paying each invoice. Without a wallet the main button connects one.
15
22
  *
16
- * Side effects: a wallet prompt; `POST permission` of the checkout.
23
+ * Each press is a try with a number: Cancel closes the window, and an answer the wallet gives later changes nothing on
24
+ * the page, except that a permission it grants still reaches Quasar. A request still open in the wallet is not asked
25
+ * again, so the buyer never approves two; what the wallet already granted is not asked again after a refusal of the free
26
+ * confirmation.
27
+ *
28
+ * Side effects: wallet prompts and, for a plain account, a transaction whose fee the buyer pays; `POST permission` of
29
+ * the checkout; network and wallet reads for the kind of account.
17
30
  *
18
31
  * @returns The automatic payments step.
19
32
  */
@@ -21,9 +34,9 @@ declare function AutoPayScreen(): react.JSX.Element | null;
21
34
 
22
35
  /**
23
36
  * The buyer details step, shown when the merchant's settings ask for the buyer and the invoice was issued without
24
- * them: the email, or the full details, and a company invoice on request (name, address, country and tax ID). The
25
- * fields carry `autocomplete` tokens (WCAG 1.3.5), errors are tied to their fields and announced, and the invoice
26
- * document is issued once the details are taken.
37
+ * them: the email, then a company invoice on request (a card under the email), then the details — the name, the
38
+ * country, the address, and for a company its tax ID. The fields carry `autocomplete` tokens (WCAG 1.3.5), errors are
39
+ * tied to their fields and announced, and the invoice document is issued once the details are taken.
27
40
  *
28
41
  * @returns The buyer details step.
29
42
  */
@@ -31,26 +44,48 @@ declare function BuyerScreen(): react.JSX.Element | null;
31
44
 
32
45
  /**
33
46
  * @file What the checkout shows for the state of a checkout store: the screen, the steps, the payment methods by
34
- * token, and when to warn about time.
47
+ * token, and when to count down and warn about time.
35
48
  */
36
49
 
37
50
  /**
38
- * A screen of the checkout: the steps of a payment (`buyer`, `method`, `pay` or `qr`, `confirm`, `autoPay`) or its
39
- * outcome.
51
+ * A screen of the checkout: the steps of a payment (`buyer`, `method`, `confirmWallet` — the paying wallet confirms the
52
+ * invoice with a free signature before the price —, `pay` or `qr`, `confirm`, `autoPay`), a payment Quasar could not
53
+ * confirm (`unconfirmed`: it may still arrive, so the buyer checks the wallet before paying again) or its outcome.
40
54
  */
41
- type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'pay' | 'qr' | 'confirm' | 'paid' | 'autoPay' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked';
55
+ type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'confirmWallet' | 'pay' | 'qr' | 'confirm' | 'unconfirmed' | 'paid' | 'autoPay' | 'autoPayOff' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked';
42
56
  /** Choices of the buyer that the checkout store does not hold. */
43
57
  interface CheckoutScreenChoices {
44
58
  /** Pay from a wallet in this browser (default) or scan a QR code with a phone. */
45
59
  payWith?: 'wallet' | 'qr';
46
60
  /** The buyer opened the automatic payments offer after paying the first period of a subscription. */
47
61
  autoPay?: boolean;
62
+ /** The buyer opened the screen that turns automatic payments off, while they are on. */
63
+ autoPayOff?: boolean;
48
64
  /**
49
65
  * The buyer continues on a phone: with `payWith` `qr`, the QR code of the payment page shows before any price is
50
66
  * locked (an EVM method, paid from the phone's wallet on that page).
51
67
  */
52
68
  handoff?: boolean;
69
+ /**
70
+ * The labels of the invoice's language are loaded (default `true`). Until then the checkout stays on `loading`, so
71
+ * its first screen never shows in English before the buyer's language arrives.
72
+ */
73
+ labelsReady?: boolean;
74
+ /**
75
+ * The buyer continued with a wallet that must confirm the invoice before the price (`payerProof` of the checkout
76
+ * store is `required`): the step that confirms it shows while the store waits for the signature and locks the price
77
+ * after it.
78
+ */
79
+ confirmWallet?: boolean;
53
80
  }
81
+ /**
82
+ * Whether the permission screen can open from this phase: another wallet takes over a permission from the steps before a
83
+ * payment, not from an outcome that keeps its own screen.
84
+ *
85
+ * @param phase - The phase of the checkout store.
86
+ * @returns Whether "Use this wallet" leads somewhere.
87
+ */
88
+ declare const takeOverOpens: (phase: string | undefined) => boolean;
54
89
  /**
55
90
  * The screen for the state of a checkout store.
56
91
  *
@@ -58,16 +93,27 @@ interface CheckoutScreenChoices {
58
93
  * @param state.phase - Where the payment stands.
59
94
  * @param state.checkout - What the checkout token opens; `null` until loaded.
60
95
  * @param state.quote - The locked price; while the first one is being locked the method screen stays, with its button
61
- * busy, so a refused payer or a failed request is shown where the buyer chose.
96
+ * busy, so a refused payer or a failed request is shown where the buyer chose (the step that confirms the wallet, when
97
+ * the price is locked after it).
98
+ * @param state.payerProof - Whether the connected wallet must confirm the invoice (`payerProof` of the checkout store;
99
+ * left out by older stores).
100
+ * @param state.error - The store's last error: a price refused after the signature shows on the method step.
62
101
  * @param choices - What the buyer chose on the page.
63
- * @returns The screen: `qr` instead of `pay` when the buyer pays with a QR code (or the price was locked without a
64
- * payer), `replaced` for an invoice the seller
65
- * corrected, `autoPay` after a paid subscription period while the automatic payments offer is open.
102
+ * @returns The screen: `confirmWallet` once the buyer continued (`choices.confirmWallet`) while the wallet must
103
+ * confirm the invoice or confirms it, and after it until the price is locked (unless it was refused), also on an
104
+ * underpaid invoice whose rest another wallet pays, `qr` instead of `pay` when the buyer pays
105
+ * with a QR code (or the price was locked without a payer), `replaced` for an invoice the seller
106
+ * corrected, `autoPay` after a paid subscription period while the automatic payments offer is open, `loading` until
107
+ * the labels of the invoice's language are loaded, `unconfirmed` in the phase of that name of a current
108
+ * `@tuwaio/quasar-sdk` (Quasar could not confirm the payment, which may still arrive). While the store hands a transaction
109
+ * over again (`submit_retrying`) it is `confirm`: only Quasar is out of reach, and the payment goes on.
66
110
  */
67
111
  declare function checkoutScreen(state: {
68
112
  phase: CheckoutPhase;
69
113
  checkout: CheckoutView | null;
70
114
  quote?: CheckoutQuote | null;
115
+ readonly payerProof?: string;
116
+ error?: CheckoutError | null;
71
117
  }, choices?: CheckoutScreenChoices): CheckoutScreen;
72
118
  /** A step of the stepper in the checkout header. */
73
119
  interface CheckoutStep {
@@ -87,6 +133,17 @@ interface CheckoutStep {
87
133
  declare function checkoutSteps(screen: CheckoutScreen, options?: {
88
134
  withDetails?: boolean;
89
135
  }): CheckoutStep[] | null;
136
+ /**
137
+ * The steps of the stepper on the paid screen of a payment page, all done. Elsewhere that screen has no stepper
138
+ * ({@link checkoutSteps}).
139
+ *
140
+ * @param options - Steps that apply to this invoice.
141
+ * @param options.withDetails - The checkout asked for the buyer details first.
142
+ * @returns The steps.
143
+ */
144
+ declare function paidSteps(options?: {
145
+ withDetails?: boolean;
146
+ }): CheckoutStep[];
90
147
  /** The methods of one token, as the method step shows it: the token first, then its network. */
91
148
  interface CheckoutTokenGroup {
92
149
  /** Token symbol. */
@@ -99,7 +156,7 @@ interface CheckoutTokenGroup {
99
156
  inWallet: boolean;
100
157
  }
101
158
  /**
102
- * Groups payment methods by token: the token picked first, then its network (decision of 2026-10-10). Groups with a
159
+ * Groups payment methods by token: the token picked first, then its network. Groups with a
103
160
  * method on the connected wallet's network come first, then those the merchant marks Popular; otherwise the
104
161
  * merchant's order stays.
105
162
  *
@@ -108,19 +165,76 @@ interface CheckoutTokenGroup {
108
165
  * @returns The groups.
109
166
  */
110
167
  declare function groupMethodsByToken(methods: CheckoutMethod[], walletChainId?: string | null): CheckoutTokenGroup[];
168
+ /**
169
+ * Where the invoice deadline stands for the checkout: the countdown shows through every step of the payment, also while
170
+ * the wallet signs, the payment is handed to Quasar and it confirms, and on a payer the wallet check refused
171
+ * (`blocked`, where the buyer can pay with another wallet); it ends with the paid outcome and with the outcomes in which
172
+ * a deadline means nothing. A payment sent before the deadline counts: Quasar keeps an `open` or `underpaid` invoice
173
+ * while a payment it learned of before the deadline confirms (for a limited time), and holds a payment that lands after
174
+ * the invoice closed for the seller to accept or return.
175
+ *
176
+ * @param status - The invoice state (`checkout.invoice.status`).
177
+ * @param screen - The screen shown.
178
+ * @param restPayable - Whether the rest of an underpaid invoice can be paid (`invoice.restPayable`).
179
+ * @returns `paying` while the buyer can still pay (the countdown shows and screen readers hear the minutes left),
180
+ * `confirming` while the payment is on its way (the countdown shows; at zero the confirm step says that the payment
181
+ * sent in time is being confirmed) and while Quasar could not confirm it (`unconfirmed`: the buyer checks the wallet
182
+ * before paying again, so no minutes left to pay are announced), or `null` once the payment succeeded (`paid`,
183
+ * `autoPay`), on the outcomes in
184
+ * which a deadline means nothing (`held`, `refunded`, `expired`, `cancelled`, `replaced`) and for an invoice that can
185
+ * no longer be paid. `closed` while part of an underpaid invoice arrived and its rest cannot be paid: the countdown still
186
+ * shows, as the time after which the seller can refund, and no minutes left to pay are announced.
187
+ */
188
+ declare function deadlineState(status: string, screen: CheckoutScreen, restPayable?: boolean): 'paying' | 'confirming' | 'closed' | null;
111
189
  /** Minutes before the invoice deadline at which screen readers hear how much time is left. */
112
190
  declare const DEADLINE_ANNOUNCEMENTS: readonly [10, 5, 1];
113
191
  /**
114
- * Whether a tick of the invoice countdown crossed one of {@link DEADLINE_ANNOUNCEMENTS}: the checkout announces the
115
- * time left then (WCAG 2.2.1), not every second.
192
+ * Whether a tick of the invoice countdown crossed one of the announcement minutes ({@link DEADLINE_ANNOUNCEMENTS} by
193
+ * default): the checkout announces the time left then (WCAG 2.2.1), not every second.
116
194
  *
117
195
  * @param previousMs - Time left at the previous tick; `null` on the first one.
118
196
  * @param ms - Time left now.
197
+ * @param announcements - The minutes before the deadline to announce at.
119
198
  * @returns The minutes to announce (the nearest when several were crossed at once), or `null`.
120
199
  */
121
- declare function deadlineAnnouncement(previousMs: number | null, ms: number): number | null;
200
+ declare function deadlineAnnouncement(previousMs: number | null, ms: number, announcements?: readonly number[]): number | null;
122
201
  /** How long before a locked price ends the checkout offers to keep it (WCAG 2.2.1: 20 seconds at least). */
123
202
  declare const QUOTE_WARNING_MS = 60000;
203
+ /**
204
+ * What the active wallet changing does to a locked price. A wallet connected to turn automatic payments off pays
205
+ * nothing, so it changes nothing while that screen is open; back on the payment, what follows applies.
206
+ *
207
+ * @param params - What the change happens over.
208
+ * @param params.autoPayOffOpen - The screen that turns automatic payments off is open.
209
+ * @param params.phase - The phase of the payment; a price is locked only in `awaitingPayment`.
210
+ * @param params.quotePayer - The payer the price is locked for.
211
+ * @param params.payer - The payer the active wallet gives for the method of that price, or `null`.
212
+ * @returns `keep`: nothing changes; `lock`: lock the price again for `payer`; `release`: release it, back to the methods.
213
+ */
214
+ declare function lockedPriceOnWallet(params: {
215
+ autoPayOffOpen: boolean;
216
+ phase: string;
217
+ quotePayer: string | null | undefined;
218
+ payer: string | null;
219
+ }): 'keep' | 'lock' | 'release';
220
+ /**
221
+ * What the active wallet changing does on the step that confirms the wallet, where no new price is locked yet: the step
222
+ * asks the wallet connected to sign, never the one the store last held.
223
+ *
224
+ * @param params - What the change happens over.
225
+ * @param params.open - The step shows.
226
+ * @param params.storePayer - The payer the store holds, which the step would ask to sign for.
227
+ * @param params.payer - The payer the active wallet gives for the chosen method, or `null`.
228
+ * @param params.paysRest - That wallet may pay: only the first wallet pays the rest of an underpaid invoice.
229
+ * @returns `keep`: nothing changes; `follow`: this wallet signs, or goes on to the price if it confirmed already; `leave`:
230
+ * the step closes, with no wallet to ask.
231
+ */
232
+ declare function walletOnConfirmStep(params: {
233
+ open: boolean;
234
+ storePayer: string | null;
235
+ payer: string | null;
236
+ paysRest: boolean;
237
+ }): 'keep' | 'follow' | 'leave';
124
238
  /**
125
239
  * Whether a locked price is in its last minute, when the checkout offers to keep it.
126
240
  *
@@ -128,6 +242,166 @@ declare const QUOTE_WARNING_MS = 60000;
128
242
  * @returns `true` from {@link QUOTE_WARNING_MS} down to the end.
129
243
  */
130
244
  declare function isQuoteEnding(ms: number): boolean;
245
+ /**
246
+ * Whether the merchant checks paying wallets before payment: `amlScreening` of the checkout, `true` when its AML mode
247
+ * is `block` or `flag`. The pay step says so only then. A checkout of a Quasar version without the field counts as
248
+ * checking, as the pay step always said before.
249
+ *
250
+ * @param checkout - What the checkout token opens.
251
+ * @returns `false` only when the checkout says that the merchant does not check paying wallets.
252
+ */
253
+ declare function screensPayingWallets(checkout: CheckoutView): boolean;
254
+ /**
255
+ * Whether a payment this page handed over is on its way: `paymentOnTheWay` of the checkout store of a current
256
+ * `@tuwaio/quasar-sdk` (`true` from a successful submit or relay, also a relay answered `sending`, which has no
257
+ * transaction key, until the payment settles or fails), else, with an older store without the field, whether the page
258
+ * handed over a transaction (`txKey` or `txHash`).
259
+ *
260
+ * @param state - The state of the checkout store.
261
+ * @param state.paymentOnTheWay - What the store says, when it has the field.
262
+ * @param state.txKey - The transaction this page submitted.
263
+ * @param state.txHash - The transaction of the payment, once known.
264
+ * @param state.error - The store's error, which names a transaction of its own when its nonce is unexplained.
265
+ * @returns Whether a payment of this page may still arrive.
266
+ */
267
+ declare function isPaymentOnTheWay(state: Pick<CheckoutState, 'txKey' | 'txHash'> & {
268
+ readonly paymentOnTheWay?: boolean;
269
+ }): boolean;
270
+ /**
271
+ * Whether Quasar reports a payment of the invoice on its way, whoever handed it over (another tab, the page before it
272
+ * was reloaded, a Solana Pay transfer Quasar found): `invoicePaymentOnTheWay` of the checkout store of a current
273
+ * `@tuwaio/quasar-sdk`, else, with an older store without the field, the `pendingPayments` of the checkout it read.
274
+ *
275
+ * @param state - The state of the checkout store.
276
+ * @param state.invoicePaymentOnTheWay - What the store says, when it has the field.
277
+ * @param checkout - What the checkout token opens; `null` until loaded.
278
+ * @returns Whether a payment of the invoice may still arrive.
279
+ */
280
+ declare function isInvoicePaymentOnTheWay(state: object & {
281
+ readonly invoicePaymentOnTheWay?: boolean;
282
+ }, checkout: CheckoutView | null): boolean;
283
+ /** What {@link sentBeforeDeadline} decides with. */
284
+ interface SentBeforeDeadlineParams {
285
+ /**
286
+ * The state of the checkout store: `paymentCountsUntil`, `paymentSentInTime` and `paymentOnTheWay` of a current
287
+ * `@tuwaio/quasar-sdk` (`txKey`/`txHash` with an older one).
288
+ */
289
+ state: object & {
290
+ readonly paymentCountsUntil?: string | null;
291
+ readonly paymentSentInTime?: boolean | null;
292
+ readonly paymentOnTheWay?: boolean;
293
+ readonly txKey?: string | null;
294
+ readonly txHash?: string | null;
295
+ };
296
+ /** The checkout: its invoice's `paymentCountsUntil` tells whether Quasar reports it, and is read with an older store. */
297
+ checkout: CheckoutView;
298
+ /** When this page handed its payment over, by its clock; `null` when it does not know (a reload, another tab). */
299
+ handedOverAt: number | null;
300
+ /** The invoice deadline (`dueAt`) in milliseconds. */
301
+ dueAt: number;
302
+ }
303
+ /**
304
+ * Whether the payment on its way counts as sent before the invoice deadline. For a payment this page handed over that
305
+ * Quasar already reported on, Quasar's word on that payment decides (`paymentSentInTime` of the checkout store: its keys
306
+ * are among the `onTimeTxKeys` Quasar learned of before `dueAt`), whatever the clock of the page says. Otherwise Quasar
307
+ * says it for the invoice with `paymentCountsUntil` (it learned of a payment of the invoice before `dueAt` and waits for
308
+ * it): its word decides, except for a payment this page handed over at or after the deadline by its clock, which Quasar
309
+ * holds even while it waits for another one. A Quasar that does not report the field leaves the clock of the page: a
310
+ * payment this page handed over before the deadline.
311
+ *
312
+ * @param params - See {@link SentBeforeDeadlineParams}.
313
+ * @returns `true` to say that the payment was sent in time and is being confirmed.
314
+ */
315
+ declare function sentBeforeDeadline({ state, checkout, handedOverAt, dueAt }: SentBeforeDeadlineParams): boolean;
316
+ /**
317
+ * Whether the last error says that the payment can never pay the invoice: `payment_failed` (reverted, cancelled…) or
318
+ * `payment_mismatch` (it does not pay the invoice: a wrong amount or recipient…), with the reason Quasar gave. A failure
319
+ * without a reason comes from a Quasar or a `@tuwaio/quasar-sdk` that cannot tell a final failure from a payment that
320
+ * may still arrive, so it does not count, nor does `settlement_failed` (a payment the network confirmed that Quasar has
321
+ * not recorded yet, which an older store reports as `payment_mismatch`).
322
+ *
323
+ * @param error - The store's error.
324
+ * @returns `true` when the payment failed for good.
325
+ */
326
+ declare function isFinalPaymentFailure(error: CheckoutError | null | undefined): boolean;
327
+ /**
328
+ * Whether the last error says that the transaction succeeded on chain but does not pay the invoice (a wrong amount,
329
+ * asset or recipient, no Solana Pay reference, sent before the price was locked…): `payment_mismatch` of a current
330
+ * `@tuwaio/quasar-sdk`, or `payment_failed` with such a reason from an older one. It may have moved money, so the
331
+ * checkout never says that it did not go through or that nothing was charged: it says that the transaction does not pay
332
+ * the invoice, and to contact the seller if money left the wallet. A payment the network confirmed that Quasar has not
333
+ * recorded yet (`settlement_failed`, which an older store reports as `payment_mismatch`) is not one: it pays the
334
+ * invoice once Quasar records it.
335
+ *
336
+ * @param error - The store's error.
337
+ * @returns `true` for a transaction that does not pay the invoice.
338
+ */
339
+ declare function isMovedMoneyFailure(error: CheckoutError | null | undefined): boolean;
340
+ /**
341
+ * Whether the last error says that Quasar credited the transaction to another invoice of the seller, the one the
342
+ * wallet that sent it confirmed or whose mark it carries (`tx_already_used` of a transaction that does not pay this
343
+ * invoice): the buyer names it to the seller if it was the payment of this invoice.
344
+ *
345
+ * @param error - The store's error.
346
+ * @returns `true` for a transaction that pays another invoice.
347
+ */
348
+ declare function isPaidElsewhere(error: CheckoutError | null | undefined): boolean;
349
+ /**
350
+ * Whether Quasar reports a payment of the invoice that may still arrive, with no time limit (one stuck past the minutes
351
+ * `pendingPayments` counts, or one whose result Quasar did not see and reads again for 24 hours):
352
+ * `invoicePaymentUnresolved` of the checkout store of a current `@tuwaio/quasar-sdk`, else the `unresolvedPayments` of
353
+ * the checkout it read. While it is `true` the checkout never says that nothing was charged.
354
+ *
355
+ * @param state - The state of the checkout store.
356
+ * @param state.invoicePaymentUnresolved - What the store says, when it has the field.
357
+ * @param checkout - What the checkout token opens; `null` until loaded.
358
+ * @returns Whether a payment of the invoice may still arrive.
359
+ */
360
+ declare function isInvoicePaymentUnresolved(state: object & {
361
+ readonly invoicePaymentUnresolved?: boolean;
362
+ }, checkout: CheckoutView | null): boolean;
363
+ /**
364
+ * What the checkout tells the buyer about a payment that may have left the wallet and that Quasar did not confirm:
365
+ * `rechecked` (Quasar still reads it again, for up to 24 hours after it learned of it, and records it for the seller if
366
+ * it arrives), `retrying` (the checkout store keeps handing over a transaction the wallet sent, which Quasar has not
367
+ * received yet: keep the page open), `notReceived` (the store gave up handing it over after an hour: Quasar never
368
+ * received it), `contact` (a reason Quasar never reads again: a relay operation lost, `transaction_failed`, a Quasar
369
+ * or a store that does not say), `closed` (Quasar saw no result on chain within 24 hours and closed it),
370
+ * `takenElsewhere` (the page of another invoice handed the transaction over first: Quasar credits it to the invoice
371
+ * that the wallet that sent it confirmed, and the page shows the result while it follows the payment),
372
+ * `settlementRetrying` (the network confirmed it, but Quasar has not recorded it yet and settles it again daily, for 30
373
+ * days after it learned of it: `rechecked`), `settlementFailed` (the same, without Quasar saying that it still
374
+ * tries) and `invoiceFull` (the invoice takes no more payments: Quasar keeps the hash for the seller and follows nothing). For all but `rechecked` and `retrying` the buyer contacts the seller with the transaction hash; after
375
+ * `takenElsewhere`, `settlementRetrying` and `settlementFailed` the payment left the wallet, so the checkout offers no
376
+ * payment.
377
+ */
378
+ type UnconfirmedFollowUp = 'nonceSpent' | 'unmined' | 'rechecked' | 'retrying' | 'notReceived' | 'contact' | 'closed' | 'takenElsewhere' | 'settlementRetrying' | 'settlementFailed' | 'invoiceFull';
379
+ /**
380
+ * What to tell the buyer about a payment Quasar did not confirm, from the store's error: `payment_unconfirmed` with
381
+ * `rechecked` (set by a current `@tuwaio/quasar-sdk` only while Quasar reads the payment again) promises the 24-hour
382
+ * re-check, its `submit_retrying` and `submit_failed` reasons are the store's hand-over, `tx_already_used` a transaction
383
+ * another invoice handed over first, any other is for the seller; `payment_failed` with the reason
384
+ * `unresolved_after_24h` is a payment Quasar closed without a result; the reason `settlement_failed` (`payment_mismatch`
385
+ * of an older store) a confirmed payment Quasar has not recorded yet, which Quasar settles again daily only while
386
+ * `rechecked` (for 30 days after it learned of it).
387
+ *
388
+ * @param error - The store's error.
389
+ * @returns See {@link UnconfirmedFollowUp}; `null` for any other error, or none.
390
+ */
391
+ declare function unconfirmedFollowUp(error: CheckoutError | null | undefined): UnconfirmedFollowUp | null;
392
+ /**
393
+ * The transaction the buyer names to the seller about a payment Quasar did not confirm: the one this page handed over
394
+ * (`txHash`, else `txKey` of the checkout store), else, on a reopened page, the newest one Quasar rejected.
395
+ *
396
+ * @param state - The state of the checkout store.
397
+ * @param state.txKey - The transaction this page submitted.
398
+ * @param state.txHash - The transaction of the payment, once known.
399
+ * @param checkout - What the checkout token opens; `null` until loaded.
400
+ * @returns The transaction hash (EVM) or signature (Solana), or `null` when the page does not know it.
401
+ */
402
+ declare function unconfirmedTxKey(state: Pick<CheckoutState, 'txKey' | 'txHash'> & {
403
+ error?: object | null;
404
+ }, checkout: CheckoutView | null): string | null;
131
405
 
132
406
  /**
133
407
  * @file Handing a payment the wallet sent over to the app's Pulsar store when the checkout closes before Quasar
@@ -160,11 +434,12 @@ interface PaymentsPulsar {
160
434
  }
161
435
  /**
162
436
  * Whether a sent payment still needs tracking when the checkout closes: Quasar has not settled it, and it did not
163
- * fail on-chain.
437
+ * fail on-chain or turn out not to pay the invoice.
164
438
  *
165
439
  * @param state - The `phase` and `error` of the checkout store.
166
440
  * @param state.phase - Where the payment stands.
167
- * @param state.error - The last failure; `payment_failed` means the transaction failed on-chain.
441
+ * @param state.error - The last failure; `payment_failed` means the transaction failed on-chain, `payment_mismatch`
442
+ * that it succeeded without paying the invoice: Quasar already has the final word on both.
168
443
  * @returns `true` to hand it over.
169
444
  */
170
445
  declare function shouldHandOver(state: {
@@ -204,6 +479,653 @@ interface HandOverParams {
204
479
  */
205
480
  declare function handOverPayment({ adapter, pulsar, payment, labels, merchant, invoice, amount, }: HandOverParams): Promise<boolean>;
206
481
 
482
+ /** Props of {@link CheckoutHeader}. */
483
+ interface CheckoutHeaderProps {
484
+ /** The heading of an outcome screen, shown instead of the steps. */
485
+ title?: ReactNode;
486
+ /** The checkout asked for the buyer details first: the steps start with them. */
487
+ withDetails?: boolean;
488
+ }
489
+ /**
490
+ * The header of the checkout: the steps (or the heading of an outcome), then the language menu and the close button,
491
+ * which stay in the top right corner on every screen and on a phone. On a phone the steps move under the order and
492
+ * the header shows the merchant.
493
+ *
494
+ * @param props - See {@link CheckoutHeaderProps}.
495
+ * @returns The header.
496
+ */
497
+ declare function CheckoutHeader({ title, withDetails }: CheckoutHeaderProps): react.JSX.Element;
498
+ /** The steps on a phone, under the order. @internal */
499
+ declare function MobileSteps({ withDetails }: {
500
+ withDetails?: boolean;
501
+ }): react.JSX.Element | null;
502
+
503
+ /** Props of {@link CheckoutStepper}. */
504
+ interface CheckoutStepperProps {
505
+ /** The steps, from `checkoutSteps`. */
506
+ steps: CheckoutStep[];
507
+ /** The labels of the checkout language. */
508
+ labels: NovaPaymentsLabels;
509
+ /** Classes added to the list. */
510
+ className?: string;
511
+ /**
512
+ * Classes added to a step (`customization.classNames.step` of `PaymentCheckout`).
513
+ *
514
+ * @param step - The step.
515
+ * @param index - Its position, from 0.
516
+ * @returns The classes, or nothing.
517
+ */
518
+ stepClassName?: (step: CheckoutStep, index: number) => string | undefined;
519
+ }
520
+ /**
521
+ * The steps of the payment, as an ordered list: done steps show a check, the current one is marked
522
+ * `aria-current="step"` and named "Step 2 of 3: Pay" to screen readers (WCAG 1.3.1). When the names of all steps do not
523
+ * fit (a phone, a long language), only the current step shows its name; screen readers still read every name.
524
+ *
525
+ * @param props - See {@link CheckoutStepperProps}.
526
+ * @returns The stepper.
527
+ */
528
+ declare function CheckoutStepper({ steps, labels, className, stepClassName }: CheckoutStepperProps): react.JSX.Element;
529
+
530
+ /** The outcomes this screen shows. */
531
+ type OutcomeKind = Extract<CheckoutScreen, 'unconfirmed' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked'>;
532
+ /**
533
+ * An outcome other than paid: a payment Quasar could not confirm (`unconfirmed`: it may still arrive, so the buyer
534
+ * checks the wallet before paying again; only while Quasar still reads it again, `error.rechecked` of the checkout
535
+ * store, the screen says that Quasar checks it for 24 hours and records it for the seller if it arrives; while the
536
+ * store hands a transaction the wallet sent over again, the buyer keeps the page open; otherwise (a reason Quasar never
537
+ * reads again, a hand-over the store gave up) the buyer contacts the seller with the transaction hash, which the screen
538
+ * shows; a transfer that moved money without paying the invoice says so, and one Quasar credited to another invoice
539
+ * says that it pays that one; a transaction the page of another invoice handed over first, which Quasar credits to the
540
+ * invoice whose quoted wallet sent it, and a payment the network confirmed that Quasar has not recorded yet are named
541
+ * with their hash for the seller, and the buyer is asked not to pay again; no payment is offered, only, on a payable
542
+ * invoice and for a payment that may not have left the wallet, "The payment did not leave my wallet", which goes back
543
+ * to it with `payAgain` of the checkout store), an
544
+ * underpaid invoice ("Pay the rest"), a payment the seller reviews (screening,
545
+ * late, overpaid, after the price lock ran out), a refunded invoice, an expired one (with what arrived before the
546
+ * deadline, which the seller can refund; never "nothing was charged" while a payment may still arrive: one this page
547
+ * handed over or saw on its way, or that the wallet sent, also after the checkout stopped following it, which Quasar
548
+ * records and shows to the seller if it arrives, one Quasar could not confirm or reports as unresolved, to check in the
549
+ * wallet, one Quasar does not read again or closed after 24 hours without a result, for the seller with its transaction
550
+ * hash, one that does not pay the invoice and may have moved money, and after a QR code showed, a payment made with it,
551
+ * as this page does not see it; while this page follows a payment on its way, until when it does, `followingUntil` of
552
+ * the checkout store), a cancelled one (the same: never "nothing was charged" while a payment may still
553
+ * arrive, also after a QR code showed, and "recorded if it arrives" only for a payment Quasar records), a corrected one
554
+ * ("Open <new invoice>" opens it here) and a payer the wallet check refused ("Use another wallet"). Each offers to
555
+ * contact the seller.
556
+ *
557
+ * @param props - The outcome.
558
+ * @param props.kind - Which outcome.
559
+ * @returns The outcome step.
560
+ */
561
+ declare function OutcomeScreen({ kind }: {
562
+ kind: OutcomeKind;
563
+ }): react.JSX.Element | null;
564
+
565
+ /** What every class name function of {@link PaymentCheckoutClassNames} receives. */
566
+ interface CheckoutPartState {
567
+ /** The screen shown. */
568
+ screen: CheckoutScreen;
569
+ /** The state of the checkout store: its phase, the chosen method, the locked price, the last error. */
570
+ checkoutState: CheckoutState;
571
+ /** The checkout, once loaded. */
572
+ checkout: CheckoutView | null;
573
+ }
574
+ /**
575
+ * Class name functions of the parts of {@link PaymentCheckout}. Each returns classes added after the default ones of
576
+ * its part (or nothing), from the state of the checkout and what the part knows; `className` of a replacement
577
+ * component (`PaymentCheckoutComponents`) gets them too. A color or size a part already sets is changed with the
578
+ * `--tuwa-*` theme variables of `@tuwaio/nova-core`, or by replacing the part: which of two classes for the same
579
+ * property wins depends on the order of the stylesheets.
580
+ */
581
+ interface PaymentCheckoutClassNames {
582
+ /**
583
+ * The checkout block with the order panel, the header and the screen (where `className` of `PaymentCheckout` goes:
584
+ * inside the dialog, or the bordered block in the page).
585
+ *
586
+ * @param params - The state of the checkout.
587
+ * @returns Classes to add.
588
+ */
589
+ container?: (params: CheckoutPartState) => string | undefined;
590
+ /**
591
+ * The order panel on the left (from 640 px).
592
+ *
593
+ * @param params - The state of the checkout.
594
+ * @returns Classes to add.
595
+ */
596
+ summary?: (params: CheckoutPartState) => string | undefined;
597
+ /**
598
+ * The order above the steps on a phone.
599
+ *
600
+ * @param params - The state of the checkout.
601
+ * @returns Classes to add.
602
+ */
603
+ compactSummary?: (params: CheckoutPartState) => string | undefined;
604
+ /**
605
+ * The header: the steps (or the heading of an outcome), the language menu and the close button.
606
+ *
607
+ * @param params - The state of the checkout.
608
+ * @returns Classes to add.
609
+ */
610
+ header?: (params: CheckoutPartState) => string | undefined;
611
+ /**
612
+ * The list of steps.
613
+ *
614
+ * @param params - The state of the checkout.
615
+ * @returns Classes to add.
616
+ */
617
+ stepper?: (params: CheckoutPartState) => string | undefined;
618
+ /**
619
+ * One step of the list.
620
+ *
621
+ * @param params - The state of the checkout and the step.
622
+ * @param params.step - The step: its key and whether it is done, current or upcoming.
623
+ * @param params.index - Its position, from 0.
624
+ * @returns Classes to add.
625
+ */
626
+ step?: (params: CheckoutPartState & {
627
+ step: CheckoutStep;
628
+ index: number;
629
+ }) => string | undefined;
630
+ /**
631
+ * The area of the screen, under the header. It scrolls in a modal and inline; on a page the window does.
632
+ *
633
+ * @param params - The state of the checkout.
634
+ * @returns Classes to add.
635
+ */
636
+ body?: (params: CheckoutPartState) => string | undefined;
637
+ /**
638
+ * The content of a step screen (buyer details, method, QR code, automatic payments), with its heading.
639
+ *
640
+ * @param params - The state of the checkout.
641
+ * @returns Classes to add.
642
+ */
643
+ screen?: (params: CheckoutPartState) => string | undefined;
644
+ /**
645
+ * The bottom of a screen, with its main button.
646
+ *
647
+ * @param params - The state of the checkout.
648
+ * @returns Classes to add.
649
+ */
650
+ footer?: (params: CheckoutPartState) => string | undefined;
651
+ /**
652
+ * The main button of a screen (Continue, Pay, Sign to pay, Pay the rest…).
653
+ *
654
+ * @param params - The state of the checkout.
655
+ * @returns Classes to add.
656
+ */
657
+ primaryButton?: (params: CheckoutPartState) => string | undefined;
658
+ /**
659
+ * The second action under the main button (back, close, not now, contact).
660
+ *
661
+ * @param params - The state of the checkout.
662
+ * @returns Classes to add.
663
+ */
664
+ secondaryButton?: (params: CheckoutPartState) => string | undefined;
665
+ /**
666
+ * A refusal or error message of a screen.
667
+ *
668
+ * @param params - The state of the checkout.
669
+ * @returns Classes to add.
670
+ */
671
+ error?: (params: CheckoutPartState) => string | undefined;
672
+ /**
673
+ * A token card of the method step.
674
+ *
675
+ * @param params - The state of the checkout and the token.
676
+ * @param params.group - The token and its methods.
677
+ * @param params.selected - Whether it is selected.
678
+ * @returns Classes to add.
679
+ */
680
+ tokenOption?: (params: CheckoutPartState & {
681
+ group: CheckoutTokenGroup;
682
+ selected: boolean;
683
+ }) => string | undefined;
684
+ /**
685
+ * A network option of the method step (when the token is on several networks).
686
+ *
687
+ * @param params - The state of the checkout and the method.
688
+ * @param params.method - The method: the token on this network.
689
+ * @param params.selected - Whether it is selected.
690
+ * @returns Classes to add.
691
+ */
692
+ networkOption?: (params: CheckoutPartState & {
693
+ method: CheckoutMethod;
694
+ selected: boolean;
695
+ }) => string | undefined;
696
+ /**
697
+ * A "Pay with" option of the method step.
698
+ *
699
+ * @param params - The state of the checkout and the option.
700
+ * @param params.payWith - `wallet` (a wallet in this browser) or `qr` (a QR code on a phone).
701
+ * @param params.selected - Whether it is selected.
702
+ * @returns Classes to add.
703
+ */
704
+ payWithOption?: (params: CheckoutPartState & {
705
+ payWith: 'wallet' | 'qr';
706
+ selected: boolean;
707
+ }) => string | undefined;
708
+ /**
709
+ * The card of the seller's consent on the method step (`checkout.consent`): the box the buyer ticks and the seller's
710
+ * words.
711
+ *
712
+ * @param params - The state of the checkout and the consent.
713
+ * @param params.checked - Whether the buyer ticked it.
714
+ * @param params.required - Whether the buyer cannot continue without ticking it.
715
+ * @returns Classes to add.
716
+ */
717
+ consentOption?: (params: CheckoutPartState & {
718
+ checked: boolean;
719
+ required: boolean;
720
+ }) => string | undefined;
721
+ /**
722
+ * A card of grouped facts (the transaction, the rate and fees, the terms of automatic payments).
723
+ *
724
+ * @param params - The state of the checkout.
725
+ * @returns Classes to add.
726
+ */
727
+ detailsCard?: (params: CheckoutPartState) => string | undefined;
728
+ /**
729
+ * A row of a card of facts (rate, network fee, recipient…).
730
+ *
731
+ * @param params - The state of the checkout.
732
+ * @returns Classes to add.
733
+ */
734
+ detailRow?: (params: CheckoutPartState) => string | undefined;
735
+ /**
736
+ * The total of the order panel.
737
+ *
738
+ * @param params - The state of the checkout.
739
+ * @returns Classes to add.
740
+ */
741
+ total?: (params: CheckoutPartState) => string | undefined;
742
+ /**
743
+ * A QR code (Solana Pay, or the payment page for a phone).
744
+ *
745
+ * @param params - The state of the checkout.
746
+ * @returns Classes to add.
747
+ */
748
+ qrCode?: (params: CheckoutPartState) => string | undefined;
749
+ /**
750
+ * The icon of an outcome other than paid.
751
+ *
752
+ * @param params - The state of the checkout and the outcome.
753
+ * @param params.kind - The outcome.
754
+ * @returns Classes to add.
755
+ */
756
+ statusIcon?: (params: CheckoutPartState & {
757
+ kind: OutcomeKind;
758
+ }) => string | undefined;
759
+ /**
760
+ * The strip and the wash of the status color along the top of the checkout, on a payment on its way and its outcome.
761
+ *
762
+ * @param params - The state of the checkout, and `tone`, the state the strip shows.
763
+ * @param params.tone - The state the strip shows.
764
+ * @returns Classes to add.
765
+ */
766
+ statusEdge?: (params: CheckoutPartState & {
767
+ tone: StatusTone;
768
+ }) => string | undefined;
769
+ }
770
+ /** Props of a replacement token card content (`PaymentCheckoutComponents.TokenOption`). */
771
+ interface CheckoutTokenOptionProps {
772
+ /** The token and its methods, one per network. */
773
+ group: CheckoutTokenGroup;
774
+ /** Whether the token is selected. */
775
+ selected: boolean;
776
+ }
777
+ /** Props of a replacement network option content (`PaymentCheckoutComponents.NetworkOption`). */
778
+ interface CheckoutNetworkOptionProps {
779
+ /** The method: the token on this network. */
780
+ method: CheckoutMethod;
781
+ /** Whether it is selected. */
782
+ selected: boolean;
783
+ }
784
+ /** Props of a replacement main button (`PaymentCheckoutComponents.PrimaryButton`): a `<button>`'s props and `busy`. */
785
+ type CheckoutPrimaryButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
786
+ /** The action is running: the default button shows the Quasar loader and is disabled. */
787
+ busy?: boolean;
788
+ };
789
+ /** Props of a replacement QR code (`PaymentCheckoutComponents.QrCode`). */
790
+ interface CheckoutQrCodeProps {
791
+ /** The text the code holds (a Solana Pay URL, or the payment page). */
792
+ value: string;
793
+ /** The text alternative of the code (WCAG 1.1.1). */
794
+ label: string;
795
+ /** The classes of the code: its size, and those of `classNames.qrCode`. */
796
+ className?: string;
797
+ }
798
+ /** Props of a replacement outcome icon (`PaymentCheckoutComponents.StatusIcon`). */
799
+ interface CheckoutStatusIconProps {
800
+ /** The outcome. */
801
+ kind: OutcomeKind;
802
+ /** The classes of `classNames.statusIcon`. */
803
+ className?: string;
804
+ }
805
+ /** Props of a replacement screen (`PaymentCheckoutComponents.screens`). */
806
+ interface CheckoutScreenProps {
807
+ /** The screen it replaces. */
808
+ screen: CheckoutScreen;
809
+ }
810
+ /**
811
+ * Components that replace parts of {@link PaymentCheckout}. A replacement reads the checkout with
812
+ * {@link useCheckoutContext} (the store, its state, the labels of the checkout language, the connected wallet and the
813
+ * actions of the steps).
814
+ */
815
+ interface PaymentCheckoutComponents {
816
+ /** The header: the steps (or the heading of an outcome), the language menu and the close button; on a phone too. */
817
+ Header?: ComponentType<CheckoutHeaderProps>;
818
+ /**
819
+ * The content of the order panel on the left (from 640 px; `classNames.summary` styles the panel around it). On a page
820
+ * the panel is a flex column as tall as the sheet.
821
+ */
822
+ Summary?: ComponentType;
823
+ /** The order above the steps on a phone; `className` holds the classes of `classNames.compactSummary`. */
824
+ CompactSummary?: ComponentType<{
825
+ className?: string;
826
+ }>;
827
+ /** The list of steps, in the header and, on a phone, under the order. */
828
+ Stepper?: ComponentType<CheckoutStepperProps>;
829
+ /** The content of a token card of the method step (the card itself stays a radio button). */
830
+ TokenOption?: ComponentType<CheckoutTokenOptionProps>;
831
+ /** The content of a network option of the method step (the option itself stays a radio button). */
832
+ NetworkOption?: ComponentType<CheckoutNetworkOptionProps>;
833
+ /** The main button of every screen. */
834
+ PrimaryButton?: ComponentType<CheckoutPrimaryButtonProps>;
835
+ /** A QR code. Keep it dark on light: scanners read inverted codes badly. */
836
+ QrCode?: ComponentType<CheckoutQrCodeProps>;
837
+ /** The icon of an outcome other than paid. */
838
+ StatusIcon?: ComponentType<CheckoutStatusIconProps>;
839
+ /** The strip and the wash of the status color along the top of the checkout (`StatusEdge` of `@tuwaio/nova-core`). */
840
+ StatusEdge?: ComponentType<StatusEdgeProps>;
841
+ /** Whole screens, by the screen they replace (for example `paid` or `loading`). */
842
+ screens?: Partial<Record<CheckoutScreen, ComponentType<CheckoutScreenProps>>>;
843
+ }
844
+ /**
845
+ * Handlers of {@link PaymentCheckout}: some wrap an action of the buyer (call `proceed()` or `select()` to run it, or
846
+ * do something else instead), the others tell the app what happened. `onPaid`, `onClose` and `onContact` are props of
847
+ * the checkout.
848
+ */
849
+ interface PaymentCheckoutHandlers {
850
+ /**
851
+ * The buyer picked a token or a network. Without the handler the method is chosen.
852
+ *
853
+ * @param params - The pick.
854
+ * @param params.method - The method picked.
855
+ * @param params.select - Chooses it.
856
+ */
857
+ onMethodSelect?: (params: {
858
+ method: CheckoutMethod;
859
+ select: () => void;
860
+ }) => void;
861
+ /**
862
+ * The buyer pressed "Continue" on the method step. Without the handler the checkout locks the price for the
863
+ * connected wallet (or connects one first), or shows the QR code.
864
+ *
865
+ * @param params - The step.
866
+ * @param params.method - The chosen method.
867
+ * @param params.payWith - `wallet` or `qr`.
868
+ * @param params.proceed - Goes on as the checkout would.
869
+ */
870
+ onQuote?: (params: {
871
+ method: CheckoutMethod;
872
+ payWith: 'wallet' | 'qr';
873
+ proceed: () => Promise<void>;
874
+ }) => void | Promise<void>;
875
+ /**
876
+ * The buyer pressed the pay button ("Pay", "Sign to pay"). Without the handler the wallet prompt opens.
877
+ *
878
+ * @param params - The payment.
879
+ * @param params.quote - The locked price: amount, recipient, network.
880
+ * @param params.method - The method.
881
+ * @param params.proceed - Opens the wallet prompt.
882
+ */
883
+ onSubmit?: (params: {
884
+ quote: CheckoutQuote;
885
+ method: CheckoutMethod;
886
+ proceed: () => Promise<void>;
887
+ }) => void | Promise<void>;
888
+ /**
889
+ * The buyer picked a language. Without the handler the checkout switches to it and saves it on the invoice.
890
+ *
891
+ * @param params - The language.
892
+ * @param params.locale - The language picked.
893
+ * @param params.proceed - Switches and saves it.
894
+ */
895
+ onLocaleChange?: (params: {
896
+ locale: CheckoutLocale;
897
+ proceed: () => Promise<void>;
898
+ }) => void | Promise<void>;
899
+ /**
900
+ * The phase of the checkout or the status of the invoice changed; also called once with the first ones.
901
+ *
902
+ * @param params - The state.
903
+ * @param params.phase - The phase of the checkout store.
904
+ * @param params.status - The invoice status, `null` before the invoice loads.
905
+ * @param params.screen - The screen shown.
906
+ */
907
+ onStatusChange?: (params: {
908
+ phase: CheckoutState['phase'];
909
+ status: CheckoutView['invoice']['status'] | null;
910
+ screen: CheckoutScreen;
911
+ }) => void;
912
+ /**
913
+ * The checkout got a new error (Quasar refused an action, or did not answer); the screen shows it.
914
+ *
915
+ * @param params - The error.
916
+ * @param params.error - Its code and message.
917
+ * @param params.screen - The screen shown.
918
+ */
919
+ onError?: (params: {
920
+ error: CheckoutError;
921
+ screen: CheckoutScreen;
922
+ }) => void;
923
+ /**
924
+ * The locked price ran out (`quote`), or the invoice expired (`invoice`). Either can happen while a payment is on its
925
+ * way: the invoice can still close while it confirms (Quasar waits for a payment it learned of
926
+ * before the deadline only for a limited time, and holds a payment that lands later for the seller to accept or
927
+ * return), so do not offer a new invoice at once when `paymentOnTheWay` is `true`; the checkout keeps following the
928
+ * invoice and shows a paid or held outcome if it changes.
929
+ *
930
+ * @param params - What expired.
931
+ * @param params.kind - `quote` or `invoice`.
932
+ * @param params.paymentOnTheWay - A payment is on its way: one this page handed over (`paymentOnTheWay` of the
933
+ * checkout store, or, with an older `@tuwaio/quasar-sdk`, a transaction handed over), one of the invoice Quasar
934
+ * reports (`invoicePaymentOnTheWay`: the page was reopened while it was on its way, another tab paid), or one Quasar
935
+ * could not confirm yet and reads again (`invoicePaymentUnresolved`).
936
+ */
937
+ onExpire?: (params: {
938
+ kind: 'quote' | 'invoice';
939
+ paymentOnTheWay: boolean;
940
+ }) => void;
941
+ }
942
+ /**
943
+ * Options of {@link PaymentCheckout}. Every text and accessible name comes from the labels, and amounts and dates
944
+ * follow the language of the checkout.
945
+ */
946
+ interface PaymentCheckoutConfig {
947
+ /** Animations. They always follow `prefers-reduced-motion`; `disabled: true` turns them off for everyone. */
948
+ animation?: {
949
+ /** Turns the animations off. */
950
+ disabled?: boolean;
951
+ };
952
+ /** Whether the header shows the steps of the payment (default `true`). */
953
+ showSteps?: boolean;
954
+ /**
955
+ * Whether the pay step reads the wallet's balance (through the chain adapter) and, when it is short, offers what the
956
+ * wallet can pay with (default `true`).
957
+ */
958
+ balanceCheck?: boolean;
959
+ /**
960
+ * Minutes before the invoice deadline at which screen readers hear the time left, while the buyer can still pay (not
961
+ * once the payment is on its way) (default `[10, 5, 1]`).
962
+ */
963
+ deadlineAnnouncements?: readonly number[];
964
+ }
965
+ /** Customization of the Nova Transactions parts the confirm and paid steps show. */
966
+ interface PaymentCheckoutChildCustomizations {
967
+ /** The status icon (`TxStatusVisual` of `@tuwaio/nova-transactions`). */
968
+ statusVisual?: Pick<TxStatusVisualProps, 'className' | 'iconClassNames'>;
969
+ /** The steps Sent, Confirming, Paid (`TxProgressIndicator` of `@tuwaio/nova-transactions`). */
970
+ progressIndicator?: Pick<TxProgressIndicatorProps, 'className' | 'stepClassNames' | 'StepComponent'>;
971
+ /** The transaction with its explorer link (`HashLink` of `@tuwaio/nova-transactions`). */
972
+ hashLink?: Pick<HashLinkProps, 'className' | 'classNames'>;
973
+ }
974
+ /** Customization of {@link PaymentCheckout} (`customization`). */
975
+ interface PaymentCheckoutCustomization {
976
+ /** Classes added to the parts, from the state of the checkout. */
977
+ classNames?: PaymentCheckoutClassNames;
978
+ /** Components that replace parts. */
979
+ components?: PaymentCheckoutComponents;
980
+ /** Handlers that wrap the actions of the buyer or tell what happened. */
981
+ handlers?: PaymentCheckoutHandlers;
982
+ /** Options: animations, steps, the balance check, the deadline announcements. */
983
+ config?: PaymentCheckoutConfig;
984
+ /** Customization of the Nova Transactions parts of the confirm and paid steps. */
985
+ childCustomizations?: PaymentCheckoutChildCustomizations;
986
+ }
987
+ /** What a part adds to {@link CheckoutPartState} for its class name function. */
988
+ type PartExtra<K extends keyof PaymentCheckoutClassNames> = Omit<Parameters<NonNullable<PaymentCheckoutClassNames[K]>>[0], keyof CheckoutPartState>;
989
+ /**
990
+ * The classes `customization.classNames` adds to a part of the checkout.
991
+ *
992
+ * @param context - The checkout context (its customization, screen, store state and checkout).
993
+ * @param part - The part.
994
+ * @param extra - What the part adds to the state, such as the method of an option.
995
+ * @returns The classes, or `undefined`.
996
+ * @internal
997
+ */
998
+ declare function checkoutClassName<K extends keyof PaymentCheckoutClassNames>(context: Pick<CheckoutContextValue, 'customization' | 'screen' | 'state' | 'checkout'>, part: K, extra?: PartExtra<K>): string | undefined;
999
+
1000
+ /** Where the checkout is shown. */
1001
+ type PaymentCheckoutDisplay = 'modal' | 'inline' | 'page';
1002
+ /** Props of {@link PaymentCheckout}. */
1003
+ interface PaymentCheckoutProps {
1004
+ /** The checkout token of the invoice (its `checkoutToken`, or the end of its `payUrl`). */
1005
+ token: string;
1006
+ /**
1007
+ * `modal` (default): a dialog over the page, 760 px wide (less on a narrower window), a sheet from the bottom under
1008
+ * 640 px; `inline`: a block in the page, as wide as its place up to 760 px; `page`: the whole page, as the Quasar
1009
+ * payment page shows it: a sheet 880 px wide, centered in the window (`min-height: 100svh`; set `--novapay-page-height`
1010
+ * on an ancestor for a page with a header of its own), that grows downward with its step and scrolls nothing inside,
1011
+ * full-bleed under 640 px.
1012
+ */
1013
+ display?: PaymentCheckoutDisplay;
1014
+ /** Whether the modal is open (`display="modal"`; default `true`). */
1015
+ open?: boolean;
1016
+ /**
1017
+ * Called when the modal opens or closes.
1018
+ *
1019
+ * @param open - The new state.
1020
+ */
1021
+ onOpenChange?: (open: boolean) => void;
1022
+ /** Called when the buyer closes the checkout; without it an inline checkout has no close button. */
1023
+ onClose?: () => void;
1024
+ /** The Quasar API; overrides `baseUrl` of `NovaPaymentsProvider`. */
1025
+ baseUrl?: string;
1026
+ /** Calls to make instead of the HTTP ones, for tests and simulations (`CheckoutApi` of `@tuwaio/quasar-sdk/checkout`). */
1027
+ api?: CheckoutApi;
1028
+ /** The `EventSource` to follow the invoice with; `null` reads it every `pollMs` (default: the browser's). */
1029
+ EventSource?: EventSourceConstructor | null;
1030
+ /** How often to read the invoice without an event stream, in milliseconds (default `5000`). */
1031
+ pollMs?: number;
1032
+ /**
1033
+ * The payment page of the invoice (its `payUrl` from the Quasar API, passed as it comes): with it, an EVM method can
1034
+ * also be paid by scanning a QR code that opens the page on a phone. `null` (a node without a dashboard URL) or
1035
+ * leaving it out offers the QR code for Solana methods only.
1036
+ */
1037
+ payUrl?: string | null;
1038
+ /**
1039
+ * Connects a wallet of a chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1040
+ * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection of `NovaPaymentsProvider`)
1041
+ * the checkout opens its connect modal instead.
1042
+ *
1043
+ * @param family - The family of the chosen method.
1044
+ */
1045
+ onConnectWallet?: (family: PaymentFamily) => void;
1046
+ /**
1047
+ * Called once when the invoice is paid (Quasar confirmed the payment). Fulfil orders from the `invoice.paid` webhook
1048
+ * on your server: this callback is for the page only.
1049
+ *
1050
+ * @param invoice - The paid invoice.
1051
+ */
1052
+ onPaid?: (invoice: CheckoutView['invoice']) => void;
1053
+ /**
1054
+ * Seconds before the paid outcome sends the buyer back to the invoice's `successUrl`, with a visible countdown and
1055
+ * "Stay here" (`0` for no automatic return). Default `5` on a page; `0` in a modal, whose paid outcome offers Close
1056
+ * instead, since the page under it is the seller's (handle the payment there with `onPaid`).
1057
+ */
1058
+ autoReturnSeconds?: number;
1059
+ /** Replaces the link of "Contact <seller>" (the seller's support email, else site) with the app's own handler. */
1060
+ onContact?: () => void;
1061
+ /** Classes added to the checkout block. */
1062
+ className?: string;
1063
+ /**
1064
+ * Class name functions of the parts, from the state of the checkout, and components that replace parts (the
1065
+ * header, the order, the steps, the options of the method step, the main button, the QR code, the outcome icon or
1066
+ * whole screens).
1067
+ */
1068
+ customization?: PaymentCheckoutCustomization;
1069
+ }
1070
+ /** The screen of the current step or outcome, or its replacement (`customization.components.screens`). @internal */
1071
+ declare function ScreenBody(): react.JSX.Element;
1072
+ /**
1073
+ * The checkout block: the order on the left (from 640 px; on a phone a compact order above the steps), the header
1074
+ * with the steps, language and close, and the current screen. The language follows the invoice, its texts the labels
1075
+ * of that language, and `lang` is set on the block (WCAG 3.1.2). Screen readers hear the time left at 10, 5 and 1
1076
+ * minutes before the deadline while the buyer can still pay. `customization` adds classes to the order and the screen area, and can replace the
1077
+ * header and the order.
1078
+ *
1079
+ * @internal
1080
+ */
1081
+ declare function CheckoutFrame({ className, withDetails, leave, }: {
1082
+ className?: string;
1083
+ withDetails?: boolean;
1084
+ leave: {
1085
+ onStay: () => void;
1086
+ onLeave: () => void;
1087
+ } | null;
1088
+ }): react.JSX.Element;
1089
+ /**
1090
+ * The checkout of a Quasar Payments invoice, opened by its checkout token: the order, the steps of the payment and
1091
+ * its outcome, in the language of the invoice. It reads the invoice with `createCheckoutStore` of
1092
+ * `@tuwaio/quasar-sdk/checkout` and follows it until it is final; no secret key reaches the browser.
1093
+ *
1094
+ * Side effects: requests to the checkout routes of the Quasar API (`baseUrl`) and an `EventSource` on the invoice
1095
+ * events while the invoice can change; changing the language saves it on the invoice (`POST locale`).
1096
+ *
1097
+ * @param props - See {@link PaymentCheckoutProps}.
1098
+ * @returns The checkout.
1099
+ *
1100
+ * @example
1101
+ * ```tsx
1102
+ * import { PaymentCheckout } from '@tuwaio/nova-payments';
1103
+ * import { useState } from 'react';
1104
+ *
1105
+ * export function PayButton({ token }: { token: string }) {
1106
+ * const [open, setOpen] = useState(false);
1107
+ * return (
1108
+ * <>
1109
+ * <button onClick={() => setOpen(true)}>Pay</button>
1110
+ * <PaymentCheckout token={token} open={open} onOpenChange={setOpen} />
1111
+ * </>
1112
+ * );
1113
+ * }
1114
+ * ```
1115
+ */
1116
+ declare function PaymentCheckout({ token, display, open, onOpenChange, onClose, baseUrl, api, EventSource, pollMs, payUrl, onConnectWallet, onPaid, autoReturnSeconds, onContact, className, customization, }: PaymentCheckoutProps): react.JSX.Element;
1117
+ /**
1118
+ * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1119
+ * no step can move its top.
1120
+ *
1121
+ * @internal
1122
+ */
1123
+ declare function CheckoutPageRoot({ label, className, children, }: {
1124
+ label: string;
1125
+ className?: string;
1126
+ children: ReactNode;
1127
+ }): react.JSX.Element;
1128
+
207
1129
  /** What the parts of a checkout share: its store and state, the screen, the language and its labels. */
208
1130
  interface CheckoutContextValue {
209
1131
  /** The checkout store of the invoice. */
@@ -220,6 +1142,18 @@ interface CheckoutContextValue {
220
1142
  labels: NovaPaymentsLabels;
221
1143
  /** `Date.now()` of the latest second tick. */
222
1144
  now: number;
1145
+ /**
1146
+ * When this page handed its current payment over (the phase became `confirming`), by the clock of the page; `null`
1147
+ * while no payment of it is confirming, or when it was already confirming as the checkout opened.
1148
+ */
1149
+ handedOverAt: number | null;
1150
+ /** The checkout showed a QR code for the invoice, which the buyer may have paid with from a phone. */
1151
+ qrShown: boolean;
1152
+ /**
1153
+ * This page handed a payment of the invoice over, or saw one on its way, and Quasar did not say that it failed for
1154
+ * good: it may still arrive, also after the store stopped following it.
1155
+ */
1156
+ paymentSent: boolean;
223
1157
  /** Closes the checkout; `undefined` when it cannot be closed (inline without `onClose`). */
224
1158
  close?: () => void;
225
1159
  /** The wallet connected through Satellite Connect, if any. */
@@ -232,8 +1166,8 @@ interface CheckoutContextValue {
232
1166
  * @param payWith - `wallet` or `qr`.
233
1167
  */
234
1168
  setPayWith: (payWith: 'wallet' | 'qr') => void;
235
- /** The payment page of the invoice (its `payUrl`), for the QR code of an EVM method. */
236
- payUrl?: string;
1169
+ /** The payment page of the invoice (its `payUrl`), for the QR code of an EVM method; `null` without one. */
1170
+ payUrl?: string | null;
237
1171
  /**
238
1172
  * Asks the buyer to connect a wallet of the method's chain family; the price is locked for it once connected.
239
1173
  *
@@ -241,6 +1175,15 @@ interface CheckoutContextValue {
241
1175
  * @returns Whether the page can connect a wallet (Nova Connect or the app's handler).
242
1176
  */
243
1177
  connectWallet: (method: CheckoutMethod) => boolean;
1178
+ /**
1179
+ * Asks the buyer to connect a wallet of a chain family and nothing more: no price is locked for it.
1180
+ *
1181
+ * @param family - The chain family.
1182
+ * @returns Whether the page can connect a wallet.
1183
+ */
1184
+ connectFamily: (family: 'eip155' | 'solana') => boolean;
1185
+ /** Whether the page opened on an invoice already paid: the buyer reads its receipt, nothing was just paid. */
1186
+ openedPaid: boolean;
244
1187
  /**
245
1188
  * The adapter that pays a chain family from the connected wallet.
246
1189
  *
@@ -258,6 +1201,24 @@ interface CheckoutContextValue {
258
1201
  setHandoff: (handoff: boolean) => void;
259
1202
  /** Goes back to the method step: forgets the locked price and the phone hand-off. */
260
1203
  backToMethods: () => void;
1204
+ /**
1205
+ * Whether the buyer continued with a wallet that must confirm the invoice before the price: the step that confirms
1206
+ * it shows while the checkout store waits for the signature (`ConfirmWalletScreen`).
1207
+ */
1208
+ confirmWallet: boolean;
1209
+ /**
1210
+ * Shows or leaves the step that confirms the wallet ("Back to methods").
1211
+ *
1212
+ * @param show - Whether it shows.
1213
+ */
1214
+ setConfirmWallet: (show: boolean) => void;
1215
+ /**
1216
+ * Locks the price for the wallet set on the checkout store, or shows the step that confirms the wallet first while
1217
+ * the store says it must (before the price).
1218
+ *
1219
+ * @returns Resolves when the price is locked, refused, or the step shows.
1220
+ */
1221
+ lockPrice: () => Promise<void>;
261
1222
  /**
262
1223
  * Remembers the payment the wallet sent: the checkout tracks it while open, and hands it over to the app's Pulsar
263
1224
  * store when it closes before Quasar settled it.
@@ -273,6 +1234,22 @@ interface CheckoutContextValue {
273
1234
  * @param autoPay - Whether it shows.
274
1235
  */
275
1236
  setAutoPay: (autoPay: boolean) => void;
1237
+ /** The screen that turns automatic payments off is open (`open`), or they were turned off (`done`). */
1238
+ autoPayOff: 'open' | 'done' | null;
1239
+ /**
1240
+ * Opens or closes the screen that turns automatic payments off, or says they were turned off.
1241
+ *
1242
+ * @param autoPayOff - The new state.
1243
+ */
1244
+ setAutoPayOff: (autoPayOff: 'open' | 'done' | null) => void;
1245
+ /** Whether the wallet has sent the transaction that revokes the permission of this invoice's subscription. */
1246
+ revokeSent: boolean;
1247
+ /**
1248
+ * Keeps that for as long as the page shows the invoice, so the buyer leaving the screen does not send it twice.
1249
+ *
1250
+ * @param sent - Whether it was sent.
1251
+ */
1252
+ setRevokeSent: (sent: boolean) => void;
276
1253
  /**
277
1254
  * Opens another invoice in this checkout: the one that replaced a corrected invoice.
278
1255
  *
@@ -283,50 +1260,18 @@ interface CheckoutContextValue {
283
1260
  onContact?: () => void;
284
1261
  /** Seconds before the paid outcome sends the buyer back to the seller; `0` for no automatic return. */
285
1262
  autoReturnSeconds: number;
1263
+ /**
1264
+ * How the checkout shows (`display` of `PaymentCheckout`): a modal belongs to the page under it, so its paid outcome
1265
+ * closes it instead of sending the buyer back to the seller's page.
1266
+ */
1267
+ display: PaymentCheckoutDisplay;
1268
+ /** Class name functions and replacement components of the parts (`customization` of `PaymentCheckout`). */
1269
+ customization: PaymentCheckoutCustomization;
286
1270
  }
287
1271
  declare const CheckoutContext: react.Context<CheckoutContextValue | null>;
288
1272
  /** Gives the parts of a checkout what they share. @internal */
289
1273
  declare const CheckoutContextProvider: react.Provider<CheckoutContextValue | null>;
290
1274
 
291
- /** Props of {@link CheckoutHeader}. */
292
- interface CheckoutHeaderProps {
293
- /** The heading of an outcome screen, shown instead of the steps. */
294
- title?: ReactNode;
295
- /** The checkout asked for the buyer details first: the steps start with them. */
296
- withDetails?: boolean;
297
- }
298
- /**
299
- * The header of the checkout: the steps (or the heading of an outcome), then the language menu and the close button,
300
- * which stay in the top right corner on every screen and on a phone. On a phone the steps move under the order and
301
- * the header shows the merchant.
302
- *
303
- * @param props - See {@link CheckoutHeaderProps}.
304
- * @returns The header.
305
- */
306
- declare function CheckoutHeader({ title, withDetails }: CheckoutHeaderProps): react.JSX.Element;
307
- /** The steps on a phone, under the order. @internal */
308
- declare function MobileSteps({ withDetails }: {
309
- withDetails?: boolean;
310
- }): react.JSX.Element | null;
311
-
312
- /** Props of {@link CheckoutStepper}. */
313
- interface CheckoutStepperProps {
314
- /** The steps, from `checkoutSteps`. */
315
- steps: CheckoutStep[];
316
- /** The labels of the checkout language. */
317
- labels: NovaPaymentsLabels;
318
- /** Classes added to the list. */
319
- className?: string;
320
- }
321
- /**
322
- * The steps of the payment, as an ordered list: done steps show a check, the current one is marked
323
- * `aria-current="step"` and named "Step 2 of 3: Pay" to screen readers (WCAG 1.3.1).
324
- *
325
- * @param props - See {@link CheckoutStepperProps}.
326
- * @returns The stepper.
327
- */
328
- declare function CheckoutStepper({ steps, labels, className }: CheckoutStepperProps): react.JSX.Element;
329
-
330
1275
  /** The merchant's logo (or the first letter of its name), name and website, and the test badge. @internal */
331
1276
  declare function MerchantBadge({ compact }: {
332
1277
  compact?: boolean;
@@ -336,7 +1281,10 @@ declare function SellerDetailsContent({ checkout, labels }: {
336
1281
  checkout: CheckoutView;
337
1282
  labels: NovaPaymentsLabels;
338
1283
  }): react.JSX.Element;
339
- /** The countdown to the invoice deadline, while the invoice can be paid. @internal */
1284
+ /**
1285
+ * The countdown to the invoice deadline, through every step of the payment until it succeeded (`deadlineState`); it
1286
+ * stays at 00:00 when the deadline passes while the payment confirms. @internal
1287
+ */
340
1288
  declare function DeadlineTimer(): react.JSX.Element | null;
341
1289
  /** The lines, subtotal and tax of the invoice. @internal */
342
1290
  declare function OrderLines(): react.JSX.Element | null;
@@ -344,35 +1292,82 @@ declare function OrderLines(): react.JSX.Element | null;
344
1292
  declare function OrderTotal(): react.JSX.Element | null;
345
1293
  /** "Secured by Quasar" and the seller's support email, at the same place on every step (WCAG 3.2.6). @internal */
346
1294
  declare function SummaryFooter(): react.JSX.Element;
1295
+ /** A button that shows or hides a part, with `aria-expanded` and `aria-controls`. @internal */
1296
+ declare function Disclosure({ label, children, className, buttonClassName, growsUp, }: {
1297
+ label: string;
1298
+ children: ReactNode;
1299
+ className?: string;
1300
+ buttonClassName?: string;
1301
+ /** The part stands at the bottom of its panel, so its content pushes the button upwards: the arrow says so. */
1302
+ growsUp?: boolean;
1303
+ }): react.JSX.Element;
347
1304
  /**
348
1305
  * The order panel on the left of the checkout (from 640 px): the merchant, the seller details (unfolded in place, the
349
- * lines scroll while the deadline and the total stay), the countdown, the lines and the total, and the help.
1306
+ * lines scroll while the deadline and the total stay), the countdown to the deadline (through every step of the
1307
+ * payment, also while it confirms, until it succeeded), the lines and the total, and the help.
350
1308
  *
351
1309
  * @returns The order panel.
352
1310
  */
353
1311
  declare function CheckoutSummary(): react.JSX.Element | null;
354
1312
  /**
355
- * The order on a phone, above the steps: the total and the countdown, with the lines and the seller details behind a
356
- * "Details" button.
1313
+ * The order on a phone, above the steps: the total and the countdown to the deadline (until the payment succeeded), with
1314
+ * the lines and the seller details behind a "Details" button.
357
1315
  *
1316
+ * @param props - The classes.
1317
+ * @param props.className - Classes added to the order (`customization.classNames.compactSummary`).
358
1318
  * @returns The compact order.
359
1319
  */
360
- declare function CompactSummary(): react.JSX.Element | null;
1320
+ declare function CompactSummary({ className }?: {
1321
+ className?: string;
1322
+ }): react.JSX.Element | null;
361
1323
 
362
1324
  /**
363
1325
  * The confirm step: the transaction is on its way and Quasar follows it until it is final. It reuses the status and
364
1326
  * progress of Nova Transactions (Sent → Confirming → Paid, in the language of the checkout) and shows the network, the
365
1327
  * amount, the transaction with its explorer link and the sender. The buyer may close the window: the payment keeps
366
- * going.
1328
+ * going. It also shows a payment of the invoice that this page did not hand over while Quasar reports it on its way
1329
+ * (the page was reopened or reloaded, another tab paid, Quasar found a Solana Pay transfer), instead of offering to pay
1330
+ * again: its note asks the buyer to wait for it. When the invoice deadline passes while a payment is on its way (the
1331
+ * countdown of the order stays at 00:00), and the invoice is still `open` or `underpaid`, the note follows the payment:
1332
+ * sent before the deadline, it says that the payment was sent in time and is being confirmed (Quasar keeps the invoice
1333
+ * open for a payment it learned of before the deadline while it confirms: for this page's payment Quasar's word on it
1334
+ * decides, `paymentSentInTime` of the checkout store, whatever the clock of the page says; else `paymentCountsUntil`;
1335
+ * with a Quasar that reports neither, a payment this page handed over before the deadline by its clock); otherwise it
1336
+ * says that the seller accepts or returns a payment that arrives after the invoice closes. A payment that failed or settled is no
1337
+ * longer on its way, and the usual note comes back. While the store hands the transaction over again, as Quasar is out of
1338
+ * reach for a moment, the note asks to keep the page open: closing it is what could lose the hand-over.
367
1339
  *
368
1340
  * @returns The confirm step.
369
1341
  */
370
1342
  declare function ConfirmScreen(): react.JSX.Element;
371
1343
 
1344
+ /**
1345
+ * The step that confirms the paying wallet, right after the wallet and the method and before
1346
+ * the price, for an EVM payment the buyer's wallet sends itself (`payerProof` of the checkout store is `required`): one
1347
+ * sentence that it is free and moves no money, the summary of what the wallet signs (the invoice, the seller, the
1348
+ * amount and the wallet), and the main button that opens the wallet's signature request. Meanwhile the window of the
1349
+ * wallet covers the step, with the site the message names to check, a line that the wallet may show it as a sign-in
1350
+ * request for that site, and "Try again" (signing again moves no money); a smart wallet is said to ask for its passkey.
1351
+ * Once the window is closed the button works again, also while the wallet never answered. A refusal keeps the buyer
1352
+ * on the step, with its reason and the same button to try again; "Back to methods" returns to the methods (or to the
1353
+ * underpaid invoice whose rest another wallet pays). Once the wallet signed, the price is locked on this step and the
1354
+ * pay step follows. One signature per invoice and wallet: a new price or token needs no new one, nor a new network for
1355
+ * an ordinary wallet (a smart wallet's signature counts on its network only).
1356
+ *
1357
+ * Side effects: wallet prompts (a network switch, the signature); `POST payer-proof/message`, `POST payer-proof` and
1358
+ * `POST quote` through the checkout store.
1359
+ *
1360
+ * @returns The step.
1361
+ */
1362
+ declare function ConfirmWalletScreen(): react.JSX.Element | null;
1363
+
372
1364
  /**
373
1365
  * The question when the buyer closes the checkout before anything is sent: the invoice stays open until its deadline,
374
- * reopened from the email or the seller's site, and the locked price is released. "Stay and pay" keeps the checkout,
375
- * "Leave" closes it. The heading takes the focus.
1366
+ * reopened from the email or the seller's site, and the locked price is released. It is a Nova dialog of its own, over
1367
+ * the checkout: one backdrop dims the whole screen, the checkout and its frame included (a layer inside the checkout
1368
+ * left its frame sharp around the dimmed content); on a phone it slides up from the bottom like the other Nova dialogs.
1369
+ * "Stay and pay", Escape or a click outside keep the checkout and give the focus back where it was, "Leave" closes it.
1370
+ * The heading takes the focus.
376
1371
  *
377
1372
  * @param props - The answers.
378
1373
  * @param props.onStay - Keeps the checkout open.
@@ -420,31 +1415,19 @@ declare function LocaleSwitcher({ locale, labels, receiptIssued, onSelect, class
420
1415
  * merchant's Popular methods next; a discount or markup of a method shows on it. Paying from a wallet needs the chain
421
1416
  * adapter of the method's family (`adapters` of `NovaPaymentsProvider`). "Continue" locks the price for the connected
422
1417
  * wallet (or connects one first), locks it without a payer for a Solana Pay QR code, or shows the QR code of the
423
- * payment page for an EVM method paid on a phone.
1418
+ * payment page for an EVM method paid on a phone; a wallet that must confirm the invoice first (an EVM payment it sends
1419
+ * itself) goes to the step that confirms it before the price. A consent the seller asks (`checkout.consent`) is a box the buyer
1420
+ * ticks under the ways to pay; a required one keeps "Continue" off until it is ticked, and the quote carries it.
424
1421
  *
425
1422
  * @returns The method step.
426
1423
  */
427
1424
  declare function MethodScreen(): react.JSX.Element | null;
428
1425
 
429
- /** The outcomes this screen shows. */
430
- type OutcomeKind = Extract<CheckoutScreen, 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked'>;
431
- /**
432
- * An outcome other than paid: an underpaid invoice ("Pay the rest"), a payment the seller reviews (screening, late,
433
- * overpaid), a refunded, expired or cancelled invoice, a corrected one ("Open <new invoice>" opens it here) and a payer
434
- * the wallet check refused ("Use another wallet"). Each offers to contact the seller.
435
- *
436
- * @param props - The outcome.
437
- * @param props.kind - Which outcome.
438
- * @returns The outcome step.
439
- */
440
- declare function OutcomeScreen({ kind }: {
441
- kind: OutcomeKind;
442
- }): react.JSX.Element | null;
443
-
444
1426
  /**
445
1427
  * The paid outcome: the amount, network, time and transaction, the steps done, a refund made later, the receipt to
446
1428
  * download, the automatic payments offer of a subscription, and the way back to the seller (`successUrl`) with a
447
- * visible countdown and "Stay here" (WCAG 2.2.1).
1429
+ * visible countdown and "Stay here" (WCAG 2.2.1). In a modal it offers Close instead: the page under it is the
1430
+ * seller's, and loading it again would close everything at once.
448
1431
  *
449
1432
  * Side effects: navigates to the seller's `successUrl` when the countdown ends.
450
1433
  *
@@ -452,130 +1435,315 @@ declare function OutcomeScreen({ kind }: {
452
1435
  */
453
1436
  declare function PaidScreen(): react.JSX.Element | null;
454
1437
 
455
- /** Where the checkout is shown. */
456
- type PaymentCheckoutDisplay = 'modal' | 'inline' | 'page';
457
- /** Props of {@link PaymentCheckout}. */
458
- interface PaymentCheckoutProps {
459
- /** The checkout token of the invoice (its `checkoutToken`, or the end of its `payUrl`). */
460
- token: string;
1438
+ /**
1439
+ * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
1440
+ * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
1441
+ * the recipient, and the main action — "Sign to pay" when the merchant pays the gas, "Pay" otherwise, "Switch to …"
1442
+ * on the wrong network, "Confirm this wallet to pay" before a transfer or a paymaster payment of a method the gasless
1443
+ * relay could pay (the wallet signs Quasar's free confirmation of the invoice first; the relay's authorization needs
1444
+ * none). Before the prompt it reads the wallet's balance (unless `config.balanceCheck` is `false`)
1445
+ * and, when it is short, offers the methods the wallet can pay and the seller's top-up link. `handlers.onSubmit` wraps
1446
+ * the pay button. A Solana payment off mainnet reminds the buyer to switch the wallet to its cluster (Solana wallets
1447
+ * choose their network themselves), with the steps of Phantom and Solflare. The note under the buttons says that the
1448
+ * payment goes straight to the merchant and, when the merchant checks paying wallets (`amlScreening` of the
1449
+ * checkout), that it does.
1450
+ *
1451
+ * Side effects: balance, fee and wallet capability reads from the network through the chain adapter (no request to
1452
+ * Quasar); wallet prompts; checkout requests to Quasar; on a Solana payment, `switchNetwork` of the Satellite store
1453
+ * moves the app's Solana connection to the payment's cluster (no wallet request).
1454
+ *
1455
+ * @returns The pay step.
1456
+ */
1457
+ declare function PayScreen(): react.JSX.Element | null;
1458
+
1459
+ /**
1460
+ * The QR code step. For Solana, a Solana Pay transfer request a phone wallet scans (or opens with "Open in wallet
1461
+ * app"), with the exact amount, the recipient, the price lock and a warning against paying from an exchange; the page
1462
+ * waits for the payment, which Quasar finds by the reference key. For an EVM method, the QR code of the payment page
1463
+ * opens this checkout on the phone, before any price.
1464
+ *
1465
+ * @returns The QR code step.
1466
+ */
1467
+ declare function QrScreen(): react.JSX.Element | null;
1468
+
1469
+ /** What a refund asks for: the amount and mode `start` takes (`RefundParams` of `@tuwaio/quasar-sdk`). */
1470
+ type RefundRequest = Parameters<RefundState['start']>[1];
1471
+ /**
1472
+ * Where a refund stands for the merchant: `amount` (what to refund), `requesting`, `connect` (a wallet of the
1473
+ * payment's network), `confirm`, `switching` and `wallet` (the wallet asks), `submitting`, `confirming` (the network
1474
+ * confirms it), `confirmed` or `failed`.
1475
+ */
1476
+ type RefundStep = 'amount' | 'requesting' | 'connect' | 'confirm' | 'switching' | 'wallet' | 'submitting' | 'confirming' | 'confirmed' | 'failed';
1477
+ /**
1478
+ * Why a refund was not sent: the wallet holds too little (`notEnough`), the merchant declined, the wallet cannot send
1479
+ * it or sent it on another network, it failed, Quasar does not know the payer (`noRecipient`), or Quasar did not answer when
1480
+ * the window looked again before asking the wallet (`unreachable`), the wallet is the one that paid and would only pay the
1481
+ * fee (`fromBuyer`), or the merchant closed the wait while the request stays open in the wallet (`stillInWallet`).
1482
+ */
1483
+ type RefundProblem = 'notEnough' | 'declined' | 'unsupported' | 'wrongNetwork' | 'failed' | 'noRecipient' | 'unreachable' | 'fromBuyer' | 'stillInWallet';
1484
+ /** What {@link useRefund} needs. */
1485
+ interface UseRefundParams {
1486
+ /** The refund store (`createRefundStore` of `@tuwaio/quasar-sdk/checkout`). */
1487
+ store: RefundStore;
1488
+ /** The paid invoice to refund. */
1489
+ invoiceId: string;
1490
+ /** Its number, for the transaction in Pulsar (the ID without one). */
1491
+ invoice?: string;
1492
+ /** The refund the app worked out: asked for at once, without the amount step. */
1493
+ params?: RefundRequest;
1494
+ /** Whether the window is open: when it opens again after a confirmed refund, it starts over for another one. */
1495
+ open?: boolean;
1496
+ /** The labels of the language. */
1497
+ labels: NovaPaymentsLabels;
1498
+ /** The language, for amounts. */
1499
+ locale: string;
461
1500
  /**
462
- * `modal` (default): a dialog over the page, a sheet from the bottom under 640 px; `inline`: a block in the page;
463
- * `page`: the block centered on its own page, as the Quasar payment page shows it.
1501
+ * Connects a wallet of the payment's chain family, for apps without Nova Connect (the `onConnectWallet` of
1502
+ * `NovaPaymentsProvider` otherwise). Inside `NovaConnectProvider` the refund opens its connect modal instead.
1503
+ *
1504
+ * @param family - The chain family of the payment.
464
1505
  */
465
- display?: PaymentCheckoutDisplay;
466
- /** Whether the modal is open (`display="modal"`; default `true`). */
467
- open?: boolean;
1506
+ onConnectWallet?: (family: PaymentFamily) => void;
1507
+ }
1508
+ /** What {@link useRefund} returns. */
1509
+ interface RefundFlow {
1510
+ /** Where the refund stands. */
1511
+ step: RefundStep;
1512
+ /** The refund store's phase. */
1513
+ phase: RefundPhase;
468
1514
  /**
469
- * Called when the modal opens or closes.
1515
+ * What a refund would send, before it is asked for: a requested refund holds its amount until it is sent.
470
1516
  *
471
- * @param open - The new state.
1517
+ * @param request - What to refund.
1518
+ * @returns The preview; `null` when the store cannot show one; `refused` when Quasar would refuse it (`error` says why).
472
1519
  */
473
- onOpenChange?: (open: boolean) => void;
474
- /** Called when the buyer closes the checkout; without it an inline checkout has no close button. */
475
- onClose?: () => void;
476
- /** The Quasar API; overrides `baseUrl` of `NovaPaymentsProvider`. */
477
- baseUrl?: string;
478
- /** Calls to make instead of the HTTP ones, for tests and simulations (`CheckoutApi` of `@tuwaio/quasar-sdk/checkout`). */
479
- api?: CheckoutApi;
480
- /** The `EventSource` to follow the invoice with; `null` reads it every `pollMs` (default: the browser's). */
481
- EventSource?: EventSourceConstructor | null;
482
- /** How often to read the invoice without an event stream, in milliseconds (default `5000`). */
483
- pollMs?: number;
1520
+ preview: (request: RefundRequest) => Promise<RefundPreview | 'refused' | null>;
1521
+ /** The refund, once asked for. */
1522
+ refund: RefundState['refund'];
1523
+ /** Why the last request to Quasar failed. */
1524
+ error: CheckoutError | null;
1525
+ /** What the wallet sends, or `null` before the refund is asked for or without a payer. */
1526
+ transfer: PaymentInstructions | null;
1527
+ /** The CAIP-2 chain of the payment. */
1528
+ chainId: string | null;
1529
+ /** The name of its network. */
1530
+ network: string;
1531
+ /** The amount to send with its symbol. */
1532
+ amount: string;
1533
+ /** The connected wallet, when it is of the payment's chain family. */
1534
+ wallet: CheckoutWallet | null;
1535
+ /** Whether the EVM wallet is on another network than the payment's: {@link RefundFlow.switchNetwork} first. */
1536
+ wrongNetwork: boolean;
1537
+ /** What the wallet holds of the asset: `undefined` while read, `null` when unknown. */
1538
+ balance: bigint | null | undefined;
1539
+ /** The estimated network fee. */
1540
+ fee: NativeFee | null | undefined;
1541
+ /** Why the refund was not sent, until the next try. */
1542
+ problem: RefundProblem | null;
1543
+ /** The transaction the wallet sent; while Quasar has not taken it, {@link RefundFlow.send} hands it over again. */
1544
+ txKey: string | null;
1545
+ /** The explorer link of a transaction of the refund, when the chain has one. */
1546
+ transactionUrl: (hash: string) => string | undefined;
1547
+ /** The explorer link of an address on the chain of the refund, when the chain has one. */
1548
+ addressUrl: (address: string) => string | undefined;
1549
+ /** Whether the page can connect a wallet. */
1550
+ canConnect: boolean;
1551
+ /** Whether the connect modal is open. */
1552
+ connecting: boolean;
484
1553
  /**
485
- * The payment page of the invoice (its `payUrl` from the Quasar API): with it, an EVM method can also be paid by
486
- * scanning a QR code that opens the page on a phone.
1554
+ * Asks Quasar for the refund.
1555
+ *
1556
+ * @param params - Amount, mode and reason.
487
1557
  */
488
- payUrl?: string;
1558
+ start: (params: RefundRequest) => Promise<void>;
1559
+ /** Asks the merchant to connect a wallet of the payment's chain family. */
1560
+ connect: () => void;
1561
+ /** Asks the EVM wallet to switch to the payment's network; sends nothing. */
1562
+ switchNetwork: () => Promise<void>;
1563
+ /** Sends the refund from the wallet (switching its network first) and hands its transaction to Quasar. */
1564
+ send: () => Promise<void>;
1565
+ /**
1566
+ * Closes the wait for the wallet. Its request stays open there: a transaction it sends later is still handed to Quasar, a
1567
+ * refusal is not shown, and {@link RefundFlow.send} asks it nothing more meanwhile.
1568
+ */
1569
+ dismiss: () => void;
1570
+ /** Whether a send is under way, from the press on: the button shows it, and another press sends nothing. */
1571
+ sending: boolean;
1572
+ }
1573
+ /**
1574
+ * Refunds a payment from the merchant's connected wallet: asks Quasar for the refund through the store,
1575
+ * sends its transfer to the payer with the payments adapter of the chain family (switching the wallet to the payment's
1576
+ * network first, and never prompting a wallet that holds too little), hands the transaction to Quasar and lets the
1577
+ * store follow it until Quasar confirms it and issues the credit note. A transaction the wallet sent is handed over
1578
+ * again on the next {@link RefundFlow.send}, never sent twice. Before the wallet is asked the refund is read again, and nothing
1579
+ * goes out when it no longer waits or Quasar does not answer. With the app's Pulsar store (`pulsar` of
1580
+ * `NovaPaymentsProvider`) and an adapter that describes its transactions, the refund is also tracked by Pulsar, and
1581
+ * Nova Transactions shows its toast.
1582
+ *
1583
+ * Side effects: the store's calls; wallet prompts; balance and fee reads from the network; the Pulsar store.
1584
+ *
1585
+ * @param params - See {@link UseRefundParams}.
1586
+ * @returns See {@link RefundFlow}.
1587
+ */
1588
+ declare function useRefund({ store, invoiceId, invoice, params, open, labels, locale, onConnectWallet, }: UseRefundParams): RefundFlow;
1589
+
1590
+ /** A refund of the store (`Refund` of `@tuwaio/quasar-sdk`). */
1591
+ type Refund = NonNullable<RefundState['refund']>;
1592
+ /** Props of {@link RefundDialog}. */
1593
+ interface RefundDialogProps {
1594
+ /** Whether the window is open. */
1595
+ open: boolean;
489
1596
  /**
490
- * Connects a wallet of a chain family, for apps without Nova Connect. Inside `NovaConnectProvider` the checkout opens
491
- * its connect modal instead.
1597
+ * Opens or closes the window.
492
1598
  *
493
- * @param family - The family of the chosen method.
1599
+ * @param open - Whether it is open.
494
1600
  */
495
- onConnectWallet?: (family: PaymentFamily) => void;
1601
+ onOpenChange: (open: boolean) => void;
496
1602
  /**
497
- * Called once when the invoice is paid (Quasar confirmed the payment). Fulfil orders from the `invoice.paid` webhook
498
- * on your server: this callback is for the page only.
1603
+ * The refund store (`createRefundStore` of `@tuwaio/quasar-sdk/checkout`), whose calls the app runs on its server
1604
+ * with the secret key. One store per invoice: it keeps the refund while the window is closed.
1605
+ */
1606
+ store: RefundStore;
1607
+ /** The paid invoice to refund. */
1608
+ invoiceId: string;
1609
+ /** Its number, shown in the title and in the transaction of Pulsar. */
1610
+ invoice?: string;
1611
+ /** The refund the app worked out (amount, mode, reason): asked for at once, without the amount step. */
1612
+ params?: RefundRequest;
1613
+ /** The invoice currency, for the amount step. Defaults to `USD`. */
1614
+ currency?: string;
1615
+ /** What is left to refund, with its currency, shown under the amount (`20.00 USD`). */
1616
+ refundable?: string;
1617
+ /** The language (a BCP 47 tag). Defaults to `en`. */
1618
+ locale?: string;
1619
+ /** Rows the app adds: to the confirm step (what the refund takes back) and to the refunded step. */
1620
+ details?: {
1621
+ confirm?: ReactNode;
1622
+ done?: ReactNode;
1623
+ };
1624
+ /** "Record refund": the app's form for a refund sent another way; offered when the wallet does not send it. */
1625
+ onRecord?: () => void;
1626
+ /**
1627
+ * Connects a wallet of the payment's chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1628
+ * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection) the window opens its
1629
+ * connect modal instead.
499
1630
  *
500
- * @param invoice - The paid invoice.
1631
+ * @param family - The chain family of the payment.
501
1632
  */
502
- onPaid?: (invoice: CheckoutView['invoice']) => void;
1633
+ onConnectWallet?: (family: PaymentFamily) => void;
503
1634
  /**
504
- * Seconds before the paid outcome sends the buyer back to the invoice's `successUrl`, with a visible countdown and
505
- * "Stay here" (default `5`; `0` for no automatic return).
1635
+ * Called once Quasar confirmed the refund and issued its credit note.
1636
+ *
1637
+ * @param refund - The confirmed refund (`Refund` of `@tuwaio/quasar-sdk`).
506
1638
  */
507
- autoReturnSeconds?: number;
508
- /** Replaces the link of "Contact <seller>" (the seller's support email, else site) with the app's own handler. */
509
- onContact?: () => void;
510
- /** Classes added to the checkout block. */
1639
+ onRefunded?: (refund: NonNullable<RefundState['refund']>) => void;
1640
+ }
1641
+ /** Props of {@link RefundButton}. */
1642
+ interface RefundButtonProps extends Omit<RefundDialogProps, 'open' | 'onOpenChange'> {
1643
+ /** The button's text. Defaults to the `refund.button` label. */
1644
+ label?: ReactNode;
1645
+ /** Classes of the button. */
511
1646
  className?: string;
1647
+ /** Whether the button is disabled. */
1648
+ disabled?: boolean;
512
1649
  }
513
1650
  /**
514
- * The checkout of a Quasar Payments invoice, opened by its checkout token: the order, the steps of the payment and
515
- * its outcome, in the language of the invoice. It reads the invoice with `createCheckoutStore` of
516
- * `@tuwaio/quasar-sdk/checkout` and follows it until it is final; no secret key reaches the browser.
517
- *
518
- * Side effects: requests to the checkout routes of the Quasar API (`baseUrl`) and an `EventSource` on the invoice
519
- * events while the invoice can change; changing the language saves it on the invoice (`POST locale`).
1651
+ * A button that refunds a paid invoice from the merchant's connected wallet: it opens {@link RefundDialog}. Put it
1652
+ * inside {@link NovaPaymentsProvider}: it uses the provider's wallet connection (the app's Satellite store and Nova
1653
+ * Connect when the app has them, else Nova's own `ownConnection`) and its adapters. In an app whose wallets connect
1654
+ * without Nova Connect, pass `onConnectWallet` here or to the provider.
520
1655
  *
521
- * @param props - See {@link PaymentCheckoutProps}.
522
- * @returns The checkout.
1656
+ * @param props - See {@link RefundButtonProps}.
1657
+ * @returns The button and its window.
523
1658
  *
524
1659
  * @example
525
1660
  * ```tsx
526
- * import { PaymentCheckout } from '@tuwaio/nova-payments';
527
- * import { useState } from 'react';
1661
+ * import { createRefundStore } from '@tuwaio/quasar-sdk/checkout';
1662
+ * import { RefundButton } from '@tuwaio/nova-payments';
528
1663
  *
529
- * export function PayButton({ token }: { token: string }) {
530
- * const [open, setOpen] = useState(false);
531
- * return (
532
- * <>
533
- * <button onClick={() => setOpen(true)}>Pay</button>
534
- * <PaymentCheckout token={token} open={open} onOpenChange={setOpen} />
535
- * </>
536
- * );
537
- * }
1664
+ * // refundInvoice, submitRefund and getRefund are Server Actions calling quasar.payments
1665
+ * const refunds = createRefundStore({ request: refundInvoice, submit: submitRefund, get: getRefund });
1666
+ *
1667
+ * <RefundButton store={refunds} invoiceId={invoice.id} invoice={invoice.number} currency="USD" />;
538
1668
  * ```
539
1669
  */
540
- declare function PaymentCheckout({ token, display, open, onOpenChange, onClose, baseUrl, api, EventSource, pollMs, payUrl, onConnectWallet, onPaid, autoReturnSeconds, onContact, className, }: PaymentCheckoutProps): react.JSX.Element;
541
-
1670
+ declare function RefundButton({ label, className, disabled, ...props }: RefundButtonProps): react.JSX.Element;
542
1671
  /**
543
- * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
544
- * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
545
- * the recipient, and the main action — "Sign to pay" when the merchant pays the gas, "Pay" otherwise, "Switch to …"
546
- * on the wrong network. Before the prompt it reads the wallet's balance and, when it is short, offers the methods
547
- * the wallet can pay and the seller's top-up link.
1672
+ * The window of a refund from the merchant's wallet: what to refund (skipped
1673
+ * with `params`), a wallet of the payment's network, the confirmation (what goes where, from which wallet with its
1674
+ * balance, the network fee, and the app's rows), the wallet's prompt, the transaction on its way, and the credit note.
1675
+ * A refund the wallet did not send says why, offers to send it again and the app's "Record refund". The refund
1676
+ * goes on while the window is closed: the store follows it.
548
1677
  *
549
- * Side effects: balance, fee and wallet capability reads from the network through the chain adapter (no request to
550
- * Quasar); wallet prompts; checkout requests to Quasar.
1678
+ * Side effects: those of `useRefund` (the store's calls, wallet prompts, balance and fee reads, the Pulsar store).
551
1679
  *
552
- * @returns The pay step.
1680
+ * @param props - See {@link RefundDialogProps}.
1681
+ * @returns The window.
553
1682
  */
554
- declare function PayScreen(): react.JSX.Element | null;
555
-
1683
+ declare function RefundDialog({ open, onOpenChange, locale, onRefunded, ...props }: RefundDialogProps): react.JSX.Element;
1684
+ /** The step of a refund the window shows. @internal */
1685
+ declare function RefundSteps({ flow, labels, locale, close, currency, refundable, details, onRecord, }: Pick<RefundDialogProps, 'currency' | 'refundable' | 'details' | 'onRecord'> & {
1686
+ flow: RefundFlow;
1687
+ labels: NovaPaymentsLabels;
1688
+ locale: string;
1689
+ close: () => void;
1690
+ }): react.JSX.Element;
1691
+ /** Whether a refund has been on its way for long, from when it last changed. @internal */
1692
+ declare const isSlow: (refund: Pick<Refund, "createdAt" | "updatedAt"> | null | undefined) => boolean;
1693
+ /** A refusal of Quasar in the words of the window, or of the app when it said it in the reader's language. @internal */
1694
+ declare const refusalText: (error: {
1695
+ code: string;
1696
+ text?: string;
1697
+ }, text: NovaPaymentsLabels["refund"]) => string;
556
1698
  /**
557
- * The QR code step. For Solana, a Solana Pay transfer request a phone wallet scans (or opens with "Open in wallet
558
- * app"), with the exact amount, the recipient, the price lock and a warning against paying from an exchange; the page
559
- * waits for the payment, which Quasar finds by the reference key. For an EVM method, the QR code of the payment page
560
- * opens this checkout on the phone, before any price.
1699
+ * A refund whose transaction failed on-chain: why, then the same refund asked for again, priced now, or recorded.
561
1700
  *
562
- * @returns The QR code step.
1701
+ * @internal
563
1702
  */
564
- declare function QrScreen(): react.JSX.Element | null;
1703
+ declare function FailedStep({ flow, labels, locale, values, recordAction, close, }: {
1704
+ flow: RefundFlow;
1705
+ labels: NovaPaymentsLabels;
1706
+ locale: string;
1707
+ values: Record<string, string>;
1708
+ recordAction: ReactNode;
1709
+ close: () => void;
1710
+ }): react.JSX.Element;
1711
+ /**
1712
+ * What to refund: an amount of the invoice currency (everything left when empty) or everything received.
1713
+ *
1714
+ * @internal
1715
+ */
1716
+ declare function AmountStep({ flow, labels, locale, currency, refundable, }: {
1717
+ flow: RefundFlow;
1718
+ labels: NovaPaymentsLabels;
1719
+ locale: string;
1720
+ currency: string;
1721
+ refundable?: string;
1722
+ }): react.JSX.Element;
1723
+ declare function ConfirmStep({ flow, labels, locale, values, details, recordAction, }: {
1724
+ flow: RefundFlow;
1725
+ labels: NovaPaymentsLabels;
1726
+ locale: string;
1727
+ values: Record<string, string>;
1728
+ details?: ReactNode;
1729
+ recordAction: ReactNode;
1730
+ }): react.JSX.Element;
565
1731
 
566
1732
  /**
567
1733
  * What the wallet asks for: a gasless signature, a transaction, a network switch, the permission of automatic
568
- * payments, or Quasar takes the payment.
1734
+ * payments, the signature that confirms the paying wallet (`proof`), or Quasar takes the payment.
569
1735
  */
570
- type WalletPromptKind = 'sign' | 'confirm' | 'switch' | 'permission' | 'submitting';
1736
+ type WalletPromptKind = 'sign' | 'confirm' | 'switch' | 'permission' | 'proof' | 'submitting';
571
1737
  /** Props of {@link WalletPrompt}. */
572
1738
  interface WalletPromptProps {
573
1739
  /** What the wallet asks for. */
574
1740
  kind: WalletPromptKind;
575
- /** The wallet's name. */
1741
+ /** The wallet's name, as it calls itself (`name` of the connected wallet). */
576
1742
  walletName: string;
577
- /** The wallet's id, for its icon. */
1743
+ /** The wallet's id, for the icon Nova has of it when the wallet gives none. */
578
1744
  walletId: string;
1745
+ /** The icon the wallet gives itself (`icon` of the connected wallet), usually a `data:` URI. */
1746
+ walletIcon?: string;
579
1747
  /** The amount with its symbol. */
580
1748
  amount: string;
581
1749
  /** The seller. */
@@ -588,19 +1756,42 @@ interface WalletPromptProps {
588
1756
  priceTime: string | null;
589
1757
  /** Asks the wallet again; only where a second request cannot pay twice (a signature). */
590
1758
  onRetry?: () => void;
1759
+ /** What the window says instead of the text of its kind (the signature that confirms the wallet). */
1760
+ text?: string;
1761
+ /** The rows to check in the wallet instead of the payment's (the signature that confirms the wallet). */
1762
+ details?: {
1763
+ name: string;
1764
+ value: string;
1765
+ }[];
1766
+ /** A line under the text: how the wallet may present the request (the signature that confirms the wallet). */
1767
+ hint?: string;
591
1768
  /** Closes the window. */
592
1769
  onCancel: () => void;
1770
+ /**
1771
+ * The height in px of the step the window stands for, measured while the step showed and capped at the room of the
1772
+ * checkout pane. Below 640 px, where the checkout has no fixed height, the window keeps it as its minimum height, so
1773
+ * the sheet does not shrink while the wallet asks and grow back after. Wider screens have the fixed height of the
1774
+ * checkout and ignore it.
1775
+ */
1776
+ stepHeight?: number | null;
593
1777
  }
594
1778
  /**
595
- * The window over the pay step while the wallet asks the buyer: what to sign or confirm, and what to check in the
596
- * wallet before — the amount, the recipient, the network and the time left of the price (WCAG 3.3.4). The heading
597
- * takes the focus, so screen readers say what happens. "Try again" re-asks only for a signature; for a transaction
598
- * the buyer is sent to the wallet, where the request still waits, so it cannot be paid twice.
1779
+ * The window that stands for the pay step while the wallet asks the buyer: what to sign or confirm, and what to check
1780
+ * in the wallet before — the amount, the recipient, the network and the time left of the price (WCAG 3.3.4); for the
1781
+ * signature that confirms the paying wallet, the invoice, the seller and the site the message names. It sits in the
1782
+ * flow of the screen, in place of the step: a screen that shows it (a custom screen of
1783
+ * `customization.components.screens` too) hides its step while it shows, with `display: none` and `inert` (the step
1784
+ * keeps its state), so the window fills the checkout pane, centered, without the scrollbar of a taller step, and
1785
+ * passes the step's height as `stepHeight`, so a phone keeps the height of the sheet. The heading takes the focus, so
1786
+ * screen readers say what happens; when the window closes and the step comes back, the focus returns to the button
1787
+ * that opened it ("Pay", "Switch to …") from the page or the dialog frame it fell back to, unless the buyer moved it
1788
+ * elsewhere. "Try again" re-asks only for a signature; for a transaction the buyer is sent to the wallet, where the
1789
+ * request still waits, so it cannot be paid twice.
599
1790
  *
600
1791
  * @param props - See {@link WalletPromptProps}.
601
1792
  * @returns The window.
602
1793
  */
603
- declare function WalletPrompt({ kind, walletName, walletId, amount, merchant, network, to, priceTime, onRetry, onCancel, }: WalletPromptProps): react.JSX.Element;
1794
+ declare function WalletPrompt({ kind, walletName, walletId, walletIcon, amount, merchant, network, to, priceTime, onRetry, text, details, hint, onCancel, stepHeight, }: WalletPromptProps): react.JSX.Element;
604
1795
 
605
1796
  /**
606
1797
  * Reads a value once per key: again when the key changes, never for a `null` key. An answer for an old key is
@@ -611,6 +1802,19 @@ declare function WalletPrompt({ kind, walletName, walletId, amount, merchant, ne
611
1802
  * @returns The value; `undefined` while it is read (or without a key); `null` when the read failed.
612
1803
  */
613
1804
  declare function useAsyncValue<T>(key: string | null, load: () => Promise<T> | T): T | null | undefined;
1805
+ /**
1806
+ * Reads a value like {@link useAsyncValue}, and again when the buyer comes back to the page (focus, visibility) or
1807
+ * `refresh` changes, keeping the last answer meanwhile: a balance the buyer tops up in the wallet opens the pay button
1808
+ * without a reload, and a read under way does not open it before the answer.
1809
+ *
1810
+ * Side effects: `focus` and `visibilitychange` listeners while there is a key.
1811
+ *
1812
+ * @param key - What the value depends on, as a string; `null` to read nothing.
1813
+ * @param load - Reads the value for the current key.
1814
+ * @param refresh - Reads again when it changes, for the same key.
1815
+ * @returns The value; `undefined` until the first answer for this key (or without a key); `null` when the read failed.
1816
+ */
1817
+ declare function useRereadValue<T>(key: string | null, load: () => Promise<T> | T, refresh?: unknown): T | null | undefined;
614
1818
 
615
1819
  /**
616
1820
  * What the parts of the surrounding `PaymentCheckout` share, for components that replace its parts.
@@ -619,6 +1823,36 @@ declare function useAsyncValue<T>(key: string | null, load: () => Promise<T> | T
619
1823
  * @throws When called outside a `PaymentCheckout`.
620
1824
  */
621
1825
  declare function useCheckoutContext(): CheckoutContextValue;
1826
+ /**
1827
+ * The context of the surrounding `PaymentCheckout`, or `null` outside one: for parts the checkout shares with
1828
+ * `RefundButton`, which take the checkout's customization only inside it.
1829
+ *
1830
+ * @returns The checkout context, or `null`.
1831
+ * @internal
1832
+ */
1833
+ declare function useOptionalCheckoutContext(): CheckoutContextValue | null;
1834
+
1835
+ /** Parameters of {@link useCheckoutEvents}. */
1836
+ interface UseCheckoutEventsParams {
1837
+ /** The state of the checkout store. */
1838
+ state: CheckoutState;
1839
+ /** The screen shown. */
1840
+ screen: CheckoutScreen;
1841
+ /** `Date.now()` of the latest second tick of the checkout. */
1842
+ now: number;
1843
+ /** The handlers of `customization.handlers` of `PaymentCheckout`. */
1844
+ handlers?: PaymentCheckoutHandlers;
1845
+ }
1846
+ /**
1847
+ * Tells the app what happened in a checkout through its handlers: `onStatusChange` with the first phase and invoice
1848
+ * status and on every change, `onError` once per new error, and `onExpire` when the locked price runs out (at the
1849
+ * tick that crosses its end) and when the invoice expires, with whether a payment is on its way (one this page handed
1850
+ * over, one of the invoice Quasar reports, as on a reopened page, or one Quasar could not confirm yet and reads again).
1851
+ * Handlers that change between renders are called in their latest version.
1852
+ *
1853
+ * @param params - See {@link UseCheckoutEventsParams}.
1854
+ */
1855
+ declare function useCheckoutEvents({ state, screen, now, handlers }: UseCheckoutEventsParams): void;
622
1856
 
623
1857
  /** What {@link useCheckoutStore} takes. */
624
1858
  interface UseCheckoutStoreOptions {
@@ -632,6 +1866,8 @@ interface UseCheckoutStoreOptions {
632
1866
  EventSource?: EventSourceConstructor | null;
633
1867
  /** How often to read the invoice without an event stream, in milliseconds. */
634
1868
  pollMs?: number;
1869
+ /** Whether to load and follow the invoice; `false` keeps the idle store, which makes no requests. Defaults to `true`. */
1870
+ enabled?: boolean;
635
1871
  }
636
1872
  /**
637
1873
  * The checkout store of an invoice (`createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`): created and loaded
@@ -656,10 +1892,15 @@ declare function useCheckoutState<T>(store: CheckoutStore, selector: (state: Che
656
1892
 
657
1893
  /**
658
1894
  * The wallet connected through Satellite Connect (the active connection of `SatelliteConnectProvider` from
659
- * `@tuwaio/satellite-react`), in CAIP identifiers; `null` without a connection or without the provider, in which case
660
- * the checkout offers the QR code and the wallet connection only.
1895
+ * `@tuwaio/satellite-react`), in CAIP identifiers, named and shown as the wallet calls itself: the name and icon of
1896
+ * its wallet in the wallet lists of the store (`getConnectors()`, the wallet with exactly the connector type of the
1897
+ * connection), as Nova Connect lists it; `null` without a connection or without the provider, in which case the
1898
+ * checkout offers the QR code and the wallet connection only.
661
1899
  *
662
- * @returns The wallet, or `null`.
1900
+ * Side effects: while mounted in the browser, a subscription to the wallet lists of the store (`watchConnectors` of
1901
+ * `@tuwaio/satellite-core`, when the store has it), so a wallet that announces itself later is named too.
1902
+ *
1903
+ * @returns The wallet, or `null`. The same object while the connection, the name and the icon stay the same.
663
1904
  */
664
1905
  declare function useConnectedWallet(): CheckoutWallet | null;
665
1906
 
@@ -683,6 +1924,55 @@ type NovaPaymentsProviderCustomization = {
683
1924
  transform?: (labels: NovaPaymentsLabels, context: NovaPaymentsLabelsContext) => NovaPaymentsLabels;
684
1925
  };
685
1926
  };
1927
+ /**
1928
+ * The wallet connection Nova brings when the app has no `SatelliteConnectProvider` above {@link NovaPaymentsProvider}:
1929
+ * a Satellite store, its watchers and a Nova Connect modal, all its own. Create it once, at module level: new adapter
1930
+ * objects on every render would be passed to the store again.
1931
+ *
1932
+ * Nova keeps one store per Satellite adapter (the first of `adapter`) for the life of the page, since the wagmi config
1933
+ * and the wallets keep their connections too: a checkout closed and opened again, another page, or a second
1934
+ * `NovaPaymentsProvider` on the same adapters shows the wallet still connected. Nova's part of the package (its
1935
+ * store and the Nova Connect modal) loads on demand, the first time a provider uses its own connection.
1936
+ */
1937
+ interface NovaPaymentsOwnConnection {
1938
+ /**
1939
+ * The Satellite adapters of Nova's store: `satelliteEVMAdapter(wagmiConfig, chains)` of `@tuwaio/satellite-evm`,
1940
+ * `satelliteSolanaAdapter({ rpcUrls })` of `@tuwaio/satellite-solana`.
1941
+ */
1942
+ adapter: SatelliteConnectProviderProps['adapter'];
1943
+ /**
1944
+ * The watchers of that store, which follow the wallets: `<EVMConnectorsWatcher wagmiConfig={wagmiConfig} />` of
1945
+ * `@tuwaio/nova-connect/evm`, `<SolanaConnectorsWatcher />` of `@tuwaio/nova-connect/solana` (without `siwx`).
1946
+ */
1947
+ watchers: ReactNode;
1948
+ /**
1949
+ * The payment adapters, on the same wagmi config as `adapter`: `paymentsEVMAdapter(wagmiConfig)`,
1950
+ * `paymentsSolanaAdapter({ rpcUrls })`.
1951
+ */
1952
+ adapters: PaymentsAdapter[];
1953
+ /**
1954
+ * The props of Nova's own connect modal (`NovaConnectProvider` of `@tuwaio/nova-connect`): `appChains` and/or
1955
+ * `solanaRPCUrls` (the modals are rendered only with them), `labels`, `legal`, `withBalance`… Never `siwx`: Nova's
1956
+ * own connection pays and refunds, it does not sign anyone in.
1957
+ */
1958
+ novaConnect: Omit<NovaConnectProviderPropsWithCustomization, 'children' | 'siwx'>;
1959
+ /**
1960
+ * Whether to reconnect the last wallet after a page load (default `false`). With `true`, Satellite's start-up runs
1961
+ * once per page load (`initializeAutoConnect` of the store): with `@tuwaio/satellite-core` 0.11.1 or later it
1962
+ * reconnects only the last wallet, without a permission prompt, and disconnects only connections this page opened;
1963
+ * earlier versions first disconnect every wallet of its adapters, which can drop the wallets of other tabs. Without it, Nova's connect modal hides "Remember this wallet", since nothing would reconnect the wallet, unless
1964
+ * `novaConnect.customization` sets `hidden` of `modals.connectModal.childComponents.rememberWallet`.
1965
+ */
1966
+ autoConnect?: boolean;
1967
+ /**
1968
+ * Whether to keep the connected wallet in `localStorage` after the tab closes (default `false`: in `sessionStorage`
1969
+ * until the tab closes). See `rememberWallet` of `createSatelliteConnectStore` from `@tuwaio/satellite-core`. The
1970
+ * keys are shared with every Satellite store of the site: connecting a wallet that is not remembered moves the last
1971
+ * connection out of `localStorage`, and disconnecting removes it, so another Satellite app on the same origin
1972
+ * forgets the wallet it remembered.
1973
+ */
1974
+ rememberWallet?: boolean;
1975
+ }
686
1976
  /** Props of {@link NovaPaymentsProvider}. */
687
1977
  interface NovaPaymentsProviderProps {
688
1978
  /** The Quasar API (Quasar Cloud by default, the address of your node for the Community Edition). */
@@ -692,9 +1982,12 @@ interface NovaPaymentsProviderProps {
692
1982
  /** Customization of the labels. */
693
1983
  customization?: NovaPaymentsProviderCustomization;
694
1984
  /**
695
- * The chain families the checkouts pay from a connected wallet on: `paymentsEVMAdapter` of
696
- * `@tuwaio/nova-payments/evm`, `paymentsSolanaAdapter` of `@tuwaio/nova-payments/solana`. Without the adapter of a
697
- * method's family, the buyer pays that method with a QR code.
1985
+ * The chain families the checkouts pay from the app's connected wallet on: `paymentsEVMAdapter` of
1986
+ * `@tuwaio/nova-payments/evm` (on the wagmi config of the app's Satellite EVM adapter), `paymentsSolanaAdapter` of
1987
+ * `@tuwaio/nova-payments/solana`. Without the adapter of a method's family, the buyer pays that method with a QR
1988
+ * code. When Nova uses its own connection, the `adapters` of `ownConnection` replace them. Without `adapters`, a
1989
+ * provider on the connection of a `NovaPaymentsProvider` above (the app's, or Nova's own) uses the adapters of that
1990
+ * provider; `[]` asks for QR codes only.
698
1991
  */
699
1992
  adapters?: PaymentsAdapter[];
700
1993
  /**
@@ -703,12 +1996,50 @@ interface NovaPaymentsProviderProps {
703
1996
  * payment goes to this store, which tracks it and keeps it in the history, and Nova Transactions shows its toast.
704
1997
  */
705
1998
  pulsar?: PaymentsPulsar;
1999
+ /**
2000
+ * The wallet connection Nova brings when the app has none: used only when no `SatelliteConnectProvider` is above
2001
+ * (see {@link NovaPaymentsOwnConnection}). Inside the app's Satellite store, Nova uses the app's connection and never
2002
+ * adds a second one.
2003
+ */
2004
+ ownConnection?: NovaPaymentsOwnConnection;
2005
+ /**
2006
+ * Connects a wallet of a chain family when there is no Nova Connect to open (an app that connects wallets its own
2007
+ * way): the default of every `PaymentCheckout`, `RefundButton` and `RefundDialog` below, which their own
2008
+ * `onConnectWallet` overrides.
2009
+ *
2010
+ * @param family - The chain family of the payment.
2011
+ */
2012
+ onConnectWallet?: (family: PaymentFamily) => void;
706
2013
  /** The app. */
707
2014
  children: ReactNode;
708
2015
  }
709
2016
  /**
710
- * Gives the checkouts below it the Quasar API, the labels and the chain adapters. A checkout works without it, with
711
- * Quasar Cloud, the built-in labels and QR payments only.
2017
+ * Gives the checkouts and refunds below it the Quasar API, the labels, the chain adapters and a wallet connection. A
2018
+ * checkout works without it, with Quasar Cloud, the built-in labels and QR payments only.
2019
+ *
2020
+ * The wallet connection is chosen once, on the first render (see {@link PaymentsConnectionMode} and
2021
+ * {@link usePaymentsConnection}): Nova brings its own connection only when the app has none.
2022
+ *
2023
+ * - Inside the app's `SatelliteConnectProvider` (from `@tuwaio/satellite-react`) and `NovaConnectProvider` (from
2024
+ * `@tuwaio/nova-connect`): the app's wallet, network, connect modal and SIWX, with the `adapters` prop. Nova mounts
2025
+ * nothing of its own.
2026
+ * - Inside the app's Satellite store without Nova Connect: the app's wallet; "Connect wallet" calls `onConnectWallet`.
2027
+ * Nova never adds a second store.
2028
+ * - Without a Satellite store, with `ownConnection`: Nova's own store, watchers and connect modal (never SIWX), with
2029
+ * the adapters of `ownConnection`. It runs Satellite's start-up only when `autoConnect` is set. That part loads on
2030
+ * demand: until it is loaded, nothing below the provider is rendered.
2031
+ * - Without either: QR payments, and `onConnectWallet`.
2032
+ *
2033
+ * A `NovaPaymentsProvider` inside another one's own connection sees that connection as the app's, so two stores never
2034
+ * stack, and without `adapters` it pays with those of the provider above. A later change of the providers above never
2035
+ * remounts the checkouts on another connection.
2036
+ *
2037
+ * Side effects: with its own connection, those of the Satellite store, kept in memory for the life of the page (the
2038
+ * last wallet in `sessionStorage`, or in `localStorage` with `rememberWallet`, under keys shared with every Satellite
2039
+ * store of the site), of the watchers and of Nova Connect. In development (`NODE_ENV` is `development`),
2040
+ * `console.warn` once when the providers above change after the first render, when `ownConnection` is given inside the
2041
+ * app's store without Nova Connect, and when `ownConnection` is given but the app's connection is used without
2042
+ * `adapters` (its own or those of a `NovaPaymentsProvider` above).
712
2043
  *
713
2044
  * @param props - See {@link NovaPaymentsProviderProps}.
714
2045
  * @returns The provider.
@@ -726,8 +2057,20 @@ interface NovaPaymentsProviderProps {
726
2057
  * }
727
2058
  * ```
728
2059
  */
729
- declare function NovaPaymentsProvider({ baseUrl, labels, customization, adapters, pulsar, children, }: NovaPaymentsProviderProps): react.JSX.Element;
2060
+ declare function NovaPaymentsProvider({ baseUrl, labels, customization, adapters, pulsar, ownConnection, onConnectWallet, children, }: NovaPaymentsProviderProps): react.JSX.Element;
730
2061
 
2062
+ /**
2063
+ * Whose wallet connection the checkouts and refunds use, as `NovaPaymentsProvider` decided on its first render:
2064
+ *
2065
+ * - `app`: the app's. A Satellite store (`SatelliteConnectProvider` of `@tuwaio/satellite-react`) and
2066
+ * `NovaConnectProvider` of `@tuwaio/nova-connect` are above it: the wallet, its network, the connect modal and SIWX
2067
+ * are the app's, and Nova adds nothing.
2068
+ * - `appStore`: the app's Satellite store without Nova Connect: "Connect wallet" calls `onConnectWallet`.
2069
+ * - `own`: Nova's own. The app has no Satellite store and gave `ownConnection`: Nova runs its own store, watchers and
2070
+ * connect modal, without SIWX.
2071
+ * - `none`: no connection. The buyer pays with a QR code, or connects through `onConnectWallet`.
2072
+ */
2073
+ type PaymentsConnectionMode = 'app' | 'appStore' | 'own' | 'none';
731
2074
  /** The settings `NovaPaymentsProvider` gives the checkouts below it. */
732
2075
  interface NovaPaymentsSettings {
733
2076
  /** The Quasar API, if set. */
@@ -736,13 +2079,27 @@ interface NovaPaymentsSettings {
736
2079
  labels?: NovaPaymentsLabelOverrides;
737
2080
  /** Customization of the labels. */
738
2081
  customization?: NovaPaymentsProviderCustomization;
739
- /** The chain families the checkouts pay from a connected wallet on. */
2082
+ /**
2083
+ * The chain families the checkouts pay from a connected wallet on: the `adapters` prop, or those of `ownConnection`
2084
+ * when Nova runs its own connection.
2085
+ */
740
2086
  adapters?: PaymentsAdapter[];
741
2087
  /** The app's Pulsar store, which takes over the payments a checkout closed on. */
742
2088
  pulsar?: PaymentsPulsar;
2089
+ /** Whose wallet connection the checkouts use; unset without `NovaPaymentsProvider`. */
2090
+ connection?: PaymentsConnectionMode;
2091
+ /**
2092
+ * The app's handler that connects a wallet, for the checkouts and refunds below without Nova Connect.
2093
+ *
2094
+ * @param family - The chain family of the payment.
2095
+ */
2096
+ onConnectWallet?: (family: PaymentFamily) => void;
743
2097
  }
744
- /** The context of `NovaPaymentsProvider`. @internal */
745
- declare const NovaPaymentsContext: react.Context<NovaPaymentsSettings>;
2098
+ /**
2099
+ * The context of `NovaPaymentsProvider`, created once and saved on `globalThis`
2100
+ * (`Symbol.for('tuwaio.nova-payments.context')`), so copies of the package share it. @internal
2101
+ */
2102
+ declare const NovaPaymentsContext: Context<NovaPaymentsSettings>;
746
2103
 
747
2104
  /**
748
2105
  * The settings of the nearest `NovaPaymentsProvider`; empty without one.
@@ -769,7 +2126,7 @@ declare function useNow(intervalMs: number, active?: boolean): number;
769
2126
  * @param invoice - The invoice of the checkout.
770
2127
  * @param onPaid - The app's callback, if any.
771
2128
  */
772
- declare function usePaidCallback(phase: CheckoutPhase, invoice: CheckoutView['invoice'] | undefined, onPaid: ((invoice: CheckoutView['invoice']) => void) | undefined): void;
2129
+ declare function usePaidCallback(phase: CheckoutPhase, invoice: CheckoutView['invoice'] | undefined, onPaid: ((invoice: CheckoutView['invoice']) => void) | undefined, openedPaid?: boolean): void;
773
2130
  /** What {@link useAutoReturn} needs. */
774
2131
  interface UseAutoReturnParams {
775
2132
  /** Where to send the buyer (the invoice's `successUrl`); `null` for no return. */
@@ -798,6 +2155,105 @@ declare function useAutoReturn({ url, seconds, now, navigate, }: UseAutoReturnPa
798
2155
  stay: () => void;
799
2156
  };
800
2157
 
2158
+ /**
2159
+ * @file Why a wallet did not pay: the buyer declined, the wallet cannot do it, it is on another network, or it failed.
2160
+ */
2161
+ /**
2162
+ * Why a wallet request did not go through: `declined` by the buyer, `unsupported` by the wallet, `wrongNetwork` when it
2163
+ * was on another network than the request, `switchFailed` when it did not switch, `notAuthorized` when it has not allowed
2164
+ * the account for the site (EIP-1193 4100), `alreadyPending` when another request of the site still waits in it,
2165
+ * `sentUnconfirmed` when it sent a payment that is not confirmed yet (it may still land), or `failed`.
2166
+ */
2167
+ type PaymentWalletErrorKind = 'declined' | 'unsupported' | 'wrongNetwork' | 'switchFailed' | 'notAuthorized' | 'alreadyPending' | 'sentUnconfirmed' | 'failed';
2168
+ /** The error a payments adapter throws when it knows why the wallet did not pay. */
2169
+ declare class PaymentWalletError extends Error {
2170
+ readonly kind: PaymentWalletErrorKind;
2171
+ /**
2172
+ * @param kind - Why: see {@link PaymentWalletErrorKind}.
2173
+ * @param message - What to log.
2174
+ * @param options - The original error as `cause`.
2175
+ */
2176
+ constructor(kind: PaymentWalletErrorKind, message: string, options?: {
2177
+ cause?: unknown;
2178
+ });
2179
+ }
2180
+ /**
2181
+ * Why a wallet request failed, from the error the wallet library threw and the causes it wraps, whichever of them names
2182
+ * it: EIP-1193 code `4001` and viem's `UserRejectedRequestError`, and the "user rejected" messages of Wallet Standard
2183
+ * wallets, are `declined`. A request the wallet already has waiting (code `-32002`) is `alreadyPending`, also inside a
2184
+ * failed switch: the buyer answers it there. wagmi's `ChainNotConfiguredError` (the network of the payment is not in the
2185
+ * wagmi config of `paymentsEVMAdapter`; the buyer can still pay with the QR code) and `ConnectorNotConnectedError` (that
2186
+ * config has no connection of the wallet) are `unsupported`, as is a wallet that does not know the request (codes 4200,
2187
+ * -32601, -32004). `ConnectorChainMismatchError` and `ChainMismatchError` are `wrongNetwork`; `SwitchChainError` and
2188
+ * `SwitchChainNotSupportedError` are `switchFailed`; code `4100` is `notAuthorized`. Named apart so that the page never
2189
+ * says a payment failed, or that a fee was spent, about a request that never left the wallet.
2190
+ *
2191
+ * Side effects: in development (`NODE_ENV` is `development`), a failure it cannot name logs to the console, and a
2192
+ * `ConnectorNotConnectedError` logs a `console.error`:
2193
+ * the app gave `NovaPaymentsProvider` an EVM adapter built on another wagmi config than the one its wallet connection
2194
+ * (its Satellite EVM adapter) uses.
2195
+ *
2196
+ * @param error - What the wallet library threw.
2197
+ * @returns The kind.
2198
+ */
2199
+ declare function walletErrorKind(error: unknown): PaymentWalletErrorKind;
2200
+
2201
+ /** Where the confirmation of the paying wallet stands: the wallet switches its network, then signs. */
2202
+ type PayerProofStep = 'idle' | 'switching' | 'signing';
2203
+ /** Why the wallet did not confirm: its kind of failure, or a network switch the buyer refused, no signature being asked. */
2204
+ type PayerProofProblem = PaymentWalletErrorKind | 'switchDeclined';
2205
+ /** What {@link usePayerProof} needs. */
2206
+ interface UsePayerProofParams {
2207
+ /** The adapter of the method's chain family; without `signMessage` the wallet cannot confirm the invoice. */
2208
+ adapter: PaymentsAdapter | undefined;
2209
+ /** The checkout store. */
2210
+ store: {
2211
+ getState: () => Pick<CheckoutState, 'confirmPayer' | 'requestQuote' | 'payer' | 'abandonConfirmation'>;
2212
+ };
2213
+ /** The connected wallet. */
2214
+ wallet: CheckoutWallet | null;
2215
+ /** The CAIP-2 network of the method: a smart wallet's signature counts there only. */
2216
+ chainId: string;
2217
+ }
2218
+ /** What {@link usePayerProof} returns. */
2219
+ interface PayerProofFlow {
2220
+ /** Where the confirmation stands. */
2221
+ step: PayerProofStep;
2222
+ /** Why the wallet did not switch or sign, until the next try; `switchDeclined`: the buyer refused the network switch. */
2223
+ problem: PayerProofProblem | null;
2224
+ /** The message Quasar issued for the wallet to sign (its site, network, nonce), once Quasar answered. */
2225
+ request: PayerProofMessage | null;
2226
+ /**
2227
+ * Confirms the invoice from the wallet: switches the wallet to the method's network when it is on another one, then
2228
+ * has it sign Quasar's message (`confirmPayer` of the checkout store).
2229
+ *
2230
+ * @param options - `quote: true` locks the price once the wallet confirmed (the step before the price).
2231
+ * @param options.quote - Whether to lock the price after it.
2232
+ * @returns Whether the wallet confirmed the invoice.
2233
+ */
2234
+ confirm: (options?: {
2235
+ quote?: boolean;
2236
+ }) => Promise<boolean>;
2237
+ /**
2238
+ * Closes the wallet window. The request stays open in the wallet: a signature it gives later still confirms the
2239
+ * invoice (and locks the price), a refusal is not shown. A cancel during the network switch asks for no signature.
2240
+ * {@link PayerProofFlow.confirm} can be called again at once: the new request replaces the open one, and signing
2241
+ * twice moves no money.
2242
+ */
2243
+ dismiss: () => void;
2244
+ }
2245
+ /**
2246
+ * Confirms that the connected wallet pays the invoice, for the step before the price and for a payment of a method the
2247
+ * gasless relay could pay: a free signature of Quasar's EIP-4361 message that moves no money, one per invoice and wallet.
2248
+ *
2249
+ * Side effects: wallet prompts (a network switch, the signature); `POST payer-proof/message` and `POST payer-proof`
2250
+ * through the checkout store, then `POST quote` with `quote: true`.
2251
+ *
2252
+ * @param params - See {@link UsePayerProofParams}.
2253
+ * @returns See {@link PayerProofFlow}.
2254
+ */
2255
+ declare function usePayerProof({ adapter, store, wallet, chainId }: UsePayerProofParams): PayerProofFlow;
2256
+
801
2257
  /**
802
2258
  * @file The payment of a locked price: how the wallet pays it, what the buyer sends and the merchant receives, the
803
2259
  * market rate behind it, and what a wallet lacks to pay it.
@@ -836,7 +2292,8 @@ interface QuoteAmounts {
836
2292
  } | null;
837
2293
  }
838
2294
  /**
839
- * What the buyer sends and the merchant receives: the same amount, unless the token keeps a fee on every transfer.
2295
+ * What the buyer sends and the merchant receives for this payment: the same amount, unless the token keeps a fee on
2296
+ * every transfer. On the quote of a rest that is what is left of the invoice, not its total.
840
2297
  *
841
2298
  * @param quote - The locked quote.
842
2299
  * @returns The amounts.
@@ -901,6 +2358,12 @@ interface PayInvoiceParams {
901
2358
  paymasterUrl: string | null;
902
2359
  /** Called when the wallet answered, before the payment is handed to Quasar. */
903
2360
  onWalletDone?: () => void;
2361
+ /**
2362
+ * Called with the ID of a sponsored batch as soon as the wallet took it, before it has a transaction.
2363
+ *
2364
+ * @param batchId - The ID of the batch.
2365
+ */
2366
+ onBatchAccepted?: (batchId: string) => void;
904
2367
  /**
905
2368
  * Called with the transaction the wallet sent (its hash), before Quasar takes it; not for a gasless signature, whose
906
2369
  * transaction Quasar sends.
@@ -912,7 +2375,8 @@ interface PayInvoiceParams {
912
2375
  /**
913
2376
  * Pays a locked quote: `transfer` sends the transfer and hands its key to Quasar (`submit`), `relay` signs the
914
2377
  * authorization for Quasar to send (`relay`), `paymaster` sends the sponsored calls and hands their transaction hash
915
- * to Quasar. A transaction the wallet sent is always handed over, whatever the page shows meanwhile.
2378
+ * to Quasar. A transaction the wallet sent is always handed over, whatever the page shows meanwhile, with the method it
2379
+ * was quoted for: the buyer may have gone on to a price on another network while the wallet asked.
916
2380
  *
917
2381
  * Side effects: a wallet prompt; requests to the checkout routes of Quasar.
918
2382
  *
@@ -921,37 +2385,28 @@ interface PayInvoiceParams {
921
2385
  * @throws {@link PaymentWalletError} `unsupported` when the adapter or the quote cannot take the path; the wallet's
922
2386
  * error when it refuses or fails.
923
2387
  */
924
- declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onSent, }: PayInvoiceParams): Promise<boolean>;
2388
+ declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onBatchAccepted, onSent, }: PayInvoiceParams): Promise<boolean>;
925
2389
 
926
2390
  /**
927
- * @file Why a wallet did not pay: the buyer declined, the wallet cannot do it, or it failed.
928
- */
929
- /** Why a wallet request did not go through. */
930
- type PaymentWalletErrorKind = 'declined' | 'unsupported' | 'failed';
931
- /** The error a payments adapter throws when it knows why the wallet did not pay. */
932
- declare class PaymentWalletError extends Error {
933
- readonly kind: PaymentWalletErrorKind;
934
- /**
935
- * @param kind - Why: `declined` by the buyer, `unsupported` by the wallet, or `failed`.
936
- * @param message - What to log.
937
- * @param options - The original error as `cause`.
938
- */
939
- constructor(kind: PaymentWalletErrorKind, message: string, options?: {
940
- cause?: unknown;
941
- });
942
- }
943
- /**
944
- * Why a wallet request failed, from the error the wallet library threw: EIP-1193 code `4001` and viem's
945
- * `UserRejectedRequestError` (also as a `cause`), and the "user rejected" messages of Wallet Standard wallets, are
946
- * `declined`.
2391
+ * How long a request the wallet never answered blocks a second one. A wallet that lost its request (a mobile session that
2392
+ * ended) gives no answer at all, and the buyer must not be trapped by it for good.
947
2393
  *
948
- * @param error - What the wallet library threw.
949
- * @returns `declined`, `unsupported` or `failed`.
2394
+ * @internal
950
2395
  */
951
- declare function walletErrorKind(error: unknown): PaymentWalletErrorKind;
2396
+ declare const OPEN_REQUEST_MS: number;
952
2397
 
953
2398
  /** Where a payment from the wallet stands: `wallet` while the wallet asks the buyer, `submitting` while Quasar takes it. */
954
2399
  type PaymentStatus = 'idle' | 'switching' | 'wallet' | 'submitting';
2400
+
2401
+ /**
2402
+ * Whether the wallet took a sponsored batch of this checkout that has no hash yet: nothing the store knows of, and still the
2403
+ * page must not say that nothing was sent.
2404
+ *
2405
+ * @param store - The checkout store.
2406
+ * @returns Whether such a batch may be on its way.
2407
+ * @internal
2408
+ */
2409
+ declare function isPaymentAccepted(store: object): boolean;
955
2410
  /** What {@link usePayment} needs. */
956
2411
  interface UsePaymentParams {
957
2412
  /** The adapter of the quote's chain family; without it the wallet cannot pay. */
@@ -966,6 +2421,8 @@ interface UsePaymentParams {
966
2421
  path: PayPath;
967
2422
  /** The checkout's ERC-7677 paymaster URL. */
968
2423
  paymasterUrl: string | null;
2424
+ /** The invoice: a sponsored batch the wallet took is kept in the tab under it until its hash comes. */
2425
+ invoiceId?: string;
969
2426
  /**
970
2427
  * Called with the payment the wallet sent (not a gasless signature, whose transaction Quasar sends).
971
2428
  *
@@ -979,6 +2436,10 @@ interface Payment {
979
2436
  status: PaymentStatus;
980
2437
  /** Why the wallet did not pay or switch, until the next try. */
981
2438
  problem: PaymentWalletErrorKind | null;
2439
+ /** The wallet asked, for the window: it keeps its name when the buyer disconnects it while the request waits there. */
2440
+ askedWallet: CheckoutWallet | null;
2441
+ /** What the wallet was asked to send, for the window: a request that waits keeps its amount under a new price. */
2442
+ askedInstructions: PaymentInstructions | null;
982
2443
  /** Pays the quote from the wallet; resolves when Quasar took it or the wallet refused. */
983
2444
  pay: () => Promise<void>;
984
2445
  /** Asks the wallet to switch to the quote's chain. */
@@ -997,7 +2458,7 @@ interface Payment {
997
2458
  * @param params - See {@link UsePaymentParams}.
998
2459
  * @returns See {@link Payment}.
999
2460
  */
1000
- declare function usePayment({ adapter, store, quote, wallet, path, paymasterUrl, onSent }: UsePaymentParams): Payment;
2461
+ declare function usePayment({ adapter, store, quote, wallet, path, paymasterUrl, invoiceId, onSent, }: UsePaymentParams): Payment;
1001
2462
 
1002
2463
  /**
1003
2464
  * What the confirm and paid steps show of the payment: its network and amount (from the locked quote), the
@@ -1008,9 +2469,13 @@ declare function usePayment({ adapter, store, quote, wallet, path, paymasterUrl,
1008
2469
  declare function usePaymentFacts(): {
1009
2470
  network: string | null;
1010
2471
  amount: string | null;
2472
+ paidAmount: string | null;
1011
2473
  txKey: string | null;
2474
+ lastOfParts: boolean;
1012
2475
  explorerUrl: string | undefined;
1013
2476
  from: string | null;
2477
+ fromAddress: string | null;
2478
+ fromUrl: string | undefined;
1014
2479
  };
1015
2480
 
1016
2481
  /** What {@link usePaymentHandOver} needs. */
@@ -1048,9 +2513,30 @@ interface UsePaymentHandOverParams {
1048
2513
  */
1049
2514
  declare function usePaymentHandOver({ store, open, adapterFor, pulsar, labels, locale, }: UsePaymentHandOverParams): (payment: SentPayment) => void;
1050
2515
 
2516
+ /**
2517
+ * Whose wallet connection the checkouts and refunds use: the choice of the nearest {@link NovaPaymentsProvider}
2518
+ * (made on its first render), or, without one, what the app's providers above give (`app`, `appStore` or `none`). See
2519
+ * {@link PaymentsConnectionMode}.
2520
+ *
2521
+ * @returns The mode.
2522
+ *
2523
+ * @example
2524
+ * ```tsx
2525
+ * import { usePaymentsConnection } from '@tuwaio/nova-payments';
2526
+ *
2527
+ * export function WalletNote() {
2528
+ * const connection = usePaymentsConnection();
2529
+ * return connection === 'own' ? <p>The checkout connects its own wallet.</p> : null;
2530
+ * }
2531
+ * ```
2532
+ */
2533
+ declare function usePaymentsConnection(): PaymentsConnectionMode;
2534
+
1051
2535
  /**
1052
2536
  * The labels of a language: the built-in ones (English for a language without its own), then `labels` of
1053
- * `NovaPaymentsProvider`, then its `customization.labels.transform`.
2537
+ * `NovaPaymentsProvider`, then its `customization.labels.transform`. The built-in labels of a language other than
2538
+ * English load on first use (see `loadLabels`); until they arrive the hook keeps the labels it showed before (English
2539
+ * the first time) and renders again once they are loaded.
1054
2540
  *
1055
2541
  * @param locale - The language of the checkout.
1056
2542
  * @returns The labels.
@@ -1073,15 +2559,17 @@ interface WalletConnection {
1073
2559
  }
1074
2560
  /**
1075
2561
  * Connects a wallet for a payment: opens the connect modal of Nova Connect on the wallets of the method's chain family
1076
- * when the checkout is inside `NovaConnectProvider` of `@tuwaio/nova-connect`, else calls the app's handler.
2562
+ * when the checkout is inside `NovaConnectProvider` of `@tuwaio/nova-connect` (the app's, or Nova's own connection of
2563
+ * {@link NovaPaymentsProvider}), else calls the app's handler: `onConnectWallet`, or that of `NovaPaymentsProvider`.
1077
2564
  *
1078
- * @param onConnectWallet - The app's handler, for apps that connect wallets without Nova Connect.
2565
+ * @param onConnectWallet - The app's handler, for apps that connect wallets without Nova Connect; overrides the
2566
+ * `onConnectWallet` of `NovaPaymentsProvider`.
1079
2567
  * @returns See {@link WalletConnection}.
1080
2568
  */
1081
2569
  declare function useWalletConnection(onConnectWallet?: (family: PaymentFamily) => void): WalletConnection;
1082
2570
 
1083
2571
  /**
1084
- * @file The buyer details the checkout collects when the merchant's settings ask for them (plan 12 §6.8): which
2572
+ * @file The buyer details the checkout collects when the merchant's settings ask for them: which
1085
2573
  * fields, what is missing, and the countries to pick from.
1086
2574
  */
1087
2575
 
@@ -1152,7 +2640,7 @@ declare function minorToDecimal(minor: string, digits?: number): string;
1152
2640
  *
1153
2641
  * @param amount - A decimal string or a number.
1154
2642
  * @param locale - BCP 47 language of the page.
1155
- * @returns The formatted amount, for example `1,234.50` in English and `1 234,50` in Russian.
2643
+ * @returns The formatted amount, for example `1,234.50` in English and `1.234,50` in German.
1156
2644
  */
1157
2645
  declare function formatFiat(amount: string | number, locale: string): string;
1158
2646
  /**
@@ -1165,6 +2653,16 @@ declare function formatFiat(amount: string | number, locale: string): string;
1165
2653
  * @returns The formatted amount, for example `89.54` for `89540000` with 6 decimals.
1166
2654
  */
1167
2655
  declare function formatTokenAmount(baseUnits: string, decimals: number, locale: string): string;
2656
+ /**
2657
+ * A network fee for a line of text: an estimate, so six decimals at most. A fee below that says nothing a reader can use
2658
+ * (the wallet sets its own and may well charge more), so it has no number.
2659
+ *
2660
+ * @param baseUnits - Base units, as a decimal integer string (not negative).
2661
+ * @param decimals - Decimals of the native token.
2662
+ * @param locale - BCP 47 language of the page.
2663
+ * @returns For example `0.000036` for 36082500481100 with 18 decimals; `null` for a fee below `0.000001`.
2664
+ */
2665
+ declare function formatFeeAmount(baseUnits: string, decimals: number, locale: string): string | null;
1168
2666
  /**
1169
2667
  * A token amount as a wallet takes it when pasted: exact, with a dot, without grouping or trailing zeros.
1170
2668
  *
@@ -1173,17 +2671,10 @@ declare function formatTokenAmount(baseUnits: string, decimals: number, locale:
1173
2671
  * @returns For example `89.54` for `89540000` with 6 decimals, `5` for `5000000`.
1174
2672
  */
1175
2673
  declare function baseUnitsToDecimal(baseUnits: string, decimals: number): string;
2674
+
1176
2675
  /**
1177
- * An address shortened to its start and end, as wallets show it.
1178
- *
1179
- * @param address - The address (`0x…` or base58).
1180
- * @param head - Characters kept at the start; `0x` counts toward it (default `6` for `0x`, `4` otherwise).
1181
- * @param tail - Characters kept at the end (default `4`).
1182
- * @returns For example `0x1111…2222`; a short address unchanged.
1183
- */
1184
- declare function shortAddress(address: string, head?: number, tail?: number): string;
1185
- /**
1186
- * Time left as a countdown: `mm:ss` under an hour, `hh:mm:ss` under a day, `Nd hh:mm:ss` beyond.
2676
+ * Time left as a countdown: `mm:ss` under an hour, `hh:mm:ss` under a day, `Nd hh:mm` beyond, where seconds say nothing
2677
+ * and would not fit beside the date in the summary.
1187
2678
  *
1188
2679
  * @param ms - Milliseconds left; a negative value counts as zero.
1189
2680
  * @returns The countdown.
@@ -1192,7 +2683,7 @@ declare function formatCountdown(ms: number): string;
1192
2683
 
1193
2684
  /**
1194
2685
  * @file What the outcome steps show: how to reach the seller, when to ask before leaving, what a refusal means, the
1195
- * terms of automatic payments, and what an underpaid invoice still needs.
2686
+ * terms of automatic payments, what an underpaid invoice still needs, and what arrived on an invoice.
1196
2687
  */
1197
2688
 
1198
2689
  /**
@@ -1205,27 +2696,55 @@ declare function formatCountdown(ms: number): string;
1205
2696
  * @returns The link, or `null` when the seller gave neither.
1206
2697
  */
1207
2698
  declare function contactHref(merchant: Pick<CheckoutMerchant, 'supportEmail' | 'website'>, subject: string): string | null;
2699
+ /**
2700
+ * What the checkout says about a payment that left the wallet, or may have, from the store's error: a transaction that
2701
+ * does not pay the invoice (`pay.mismatch`; `pay.mismatchTakenElsewhere` when Quasar credited it to another invoice;
2702
+ * `pay.mismatchHeldElsewhere` when another invoice holds it for a refund only, `held`;
2703
+ * `pay.mismatchOtherWallet` for a transfer from a wallet that did not confirm the invoice, `pay.mismatchOtherWalletHeld`
2704
+ * when Quasar recorded it as a held transfer the seller returns, `held`; `pay.mismatchChargeHeld` for an automatic charge
2705
+ * that landed after the buyer chose another way to pay), a payment Quasar closed after 24 hours without a result on chain
2706
+ * (`outcome.unconfirmedClosed`), a transaction another invoice handed over first (`outcome.unconfirmedTakenElsewhere`)
2707
+ * and a payment the network confirmed that Quasar has not recorded yet (`outcome.unconfirmedSettlementRetrying` while
2708
+ * Quasar settles it again daily, for 30 days, else `outcome.unconfirmedSettlementFailed`). Never "it failed", "only the
2709
+ * network fee was spent" or "nothing was charged" for them.
2710
+ *
2711
+ * @param error - The store's error, if any.
2712
+ * @param labels - The labels of the checkout language.
2713
+ * @param merchant - The seller's name.
2714
+ * @returns The text, or `null` for any other error, or none.
2715
+ */
2716
+ declare function leftTheWalletText(error: CheckoutError | null | undefined, labels: NovaPaymentsLabels, merchant?: string): string | null;
1208
2717
  /**
1209
2718
  * Whether closing the checkout asks first: only while nothing has been sent. Once a transaction is on its way, or the
1210
- * invoice is settled, the checkout closes without a question.
2719
+ * invoice is settled, the checkout closes without a question; also after a payment that left the wallet, or may have
2720
+ * ({@link leftTheWalletText}: a transaction that does not pay the invoice, a payment Quasar closed without a result on
2721
+ * chain within 24 hours, a transaction another invoice handed over first, a confirmed payment Quasar has not recorded
2722
+ * yet), so the question's "Nothing is sent yet" would not be true. Nor is it on the rest of an underpaid invoice, whose
2723
+ * price stays as it is.
1211
2724
  *
1212
2725
  * @param phase - Where the payment stands.
2726
+ * @param error - The store's last error, if any.
2727
+ * @param status - The state of the invoice, when known.
1213
2728
  * @returns `true` to ask.
1214
2729
  */
1215
- declare function needsLeaveConfirm(phase: CheckoutPhase): boolean;
2730
+ declare function needsLeaveConfirm(phase: CheckoutPhase, error?: CheckoutError | null, status?: string | null): boolean;
1216
2731
  /**
1217
2732
  * The text of a refusal on the method step, with what to do.
1218
2733
  *
1219
2734
  * @param error - The store's error.
1220
2735
  * @param labels - The labels of the checkout language.
2736
+ * @param merchant - The seller's name, for a payment that left the wallet, or may have ({@link leftTheWalletText}).
1221
2737
  * @returns The text.
1222
2738
  */
1223
- declare function methodErrorText(error: CheckoutError, labels: NovaPaymentsLabels): string;
2739
+ declare function methodErrorText(error: CheckoutError, labels: NovaPaymentsLabels, merchant?: string): string;
1224
2740
  /** The terms of an automatic payments offer, as the checkout shows them. */
1225
2741
  interface AutoPayTerms {
1226
2742
  /** The CAIP-2 chain of the charges. */
1227
2743
  chainId: string;
1228
- /** The account that takes the payments (the merchant's collector). */
2744
+ /**
2745
+ * The wallet the charges are paid to: the merchant's, as the `payee` rule of the request names it (the app's
2746
+ * collector, which sends the charges, when the request names no payee).
2747
+ */
1229
2748
  to: string;
1230
2749
  /** The most it takes in a period, in base units of the token. */
1231
2750
  limit: string;
@@ -1238,9 +2757,20 @@ interface AutoPayTerms {
1238
2757
  /** When the permission ends, in milliseconds; `null` without an expiry rule. */
1239
2758
  expiresAt: number | null;
1240
2759
  }
2760
+ /**
2761
+ * What the connected wallet may ask its wallet for: the offer, or taking over an active permission that holds nothing.
2762
+ *
2763
+ * @param offer - The automatic-charge offer of the checkout.
2764
+ * @returns The method and the request, or `null` when nothing can be given now.
2765
+ */
2766
+ declare function grantableOffer(offer: AutoChargeOffer | null): Extract<AutoChargeOffer, {
2767
+ status: 'available';
2768
+ }> | NonNullable<Extract<AutoChargeOffer, {
2769
+ status: 'active';
2770
+ }>['replacement']> | null;
1241
2771
  /**
1242
2772
  * The terms of an ERC-7715 automatic payments offer: the periodic limit in the token of the method, the period, the
1243
- * expiry and the accounts.
2773
+ * expiry and the merchant's wallet the charges are paid to.
1244
2774
  *
1245
2775
  * @param offer - The view's `autoCharge`.
1246
2776
  * @param methods - The view's methods (for the token of the offer).
@@ -1263,6 +2793,142 @@ declare function formatPeriod(seconds: number, locale: string): string;
1263
2793
  * @returns The rest, or `null` when it is unknown or nothing is left.
1264
2794
  */
1265
2795
  declare function underpaidRest(quote: Pick<CheckoutQuote, 'cryptoAmountExpected'> | null, amountPaid: string | null): string | null;
2796
+ /**
2797
+ * What the buyer is told about the rate of the rest of an underpaid invoice, in an asset that moves against the invoice
2798
+ * currency (`rateHeldUntil` of the quote): until when a payment settles by itself, or that the seller now decides.
2799
+ *
2800
+ * @param quote - The locked quote.
2801
+ * @param now - The time now, in milliseconds.
2802
+ * @param labels - The labels of the checkout language.
2803
+ * @param merchant - The seller's name.
2804
+ * @param locale - The language of the checkout.
2805
+ * @param ended - What is said past that time; the payment step's `pay.restRateEnded` speaks of the payment being made.
2806
+ * @returns The text, or `null` when the rate holds until the due date.
2807
+ */
2808
+ declare function restRateText(quote: Pick<CheckoutQuote, 'rateHeldUntil'> | null, now: number, labels: NovaPaymentsLabels, merchant: string, locale: string, ended?: string): string | null;
2809
+ /**
2810
+ * The address of a wallet Quasar names: it keeps the wallet that paid first as an address or as a CAIP-10 account.
2811
+ *
2812
+ * @param wallet - The wallet, in either form.
2813
+ * @returns The address.
2814
+ */
2815
+ declare function addressOfWallet(wallet: string): string;
2816
+ /**
2817
+ * Whether two wallets Quasar names are one: an EVM address in any letter case, any other exactly.
2818
+ *
2819
+ * @param a - A wallet, as an address or an account.
2820
+ * @param b - Another one.
2821
+ * @returns `true` for the same wallet.
2822
+ */
2823
+ declare function isSameWallet(a: string, b: string): boolean;
2824
+ /**
2825
+ * What arrived on an invoice, when anything did: an expired invoice says so instead of "nothing was charged".
2826
+ *
2827
+ * @param amountPaid - What arrived, in base units of the locked token (`amountPaid` of the invoice).
2828
+ * @returns The amount, or `null` when nothing arrived.
2829
+ */
2830
+ declare function receivedAmount(amountPaid: string | null): string | null;
2831
+ /**
2832
+ * Whether a refund sends more tokens than came in, or a noticeably different number of tokens than its amount took at the rate of the payment: half a
2833
+ * percent or more, so a stablecoin at par never asks.
2834
+ *
2835
+ * @param preview - What the refund would send.
2836
+ * @returns Whether the merchant should look first.
2837
+ */
2838
+ declare function refundRateMoved(preview: Pick<RefundPreview, 'cryptoAmount' | 'atPaymentRate'> & Partial<Pick<RefundPreview, 'received'>>): boolean;
2839
+ /**
2840
+ * Whether the checkout needs its second tick: for the deadline, the price lock and the return countdown. A receipt or an
2841
+ * expired page left open would otherwise render everything once a second for nothing.
2842
+ *
2843
+ * @param phase - The checkout's phase.
2844
+ * @param autoReturnSeconds - The seconds before the paid outcome returns to the seller, when set.
2845
+ * @param labelsShown - Whether the labels of the language are there: their file shows with a render.
2846
+ * @returns Whether to tick.
2847
+ * @internal
2848
+ */
2849
+ declare function needsTheClock(phase: string, autoReturnSeconds: number | undefined, labelsShown: boolean): boolean;
2850
+
2851
+ /**
2852
+ * @file The paying wallet's confirmation of the invoice: before an EVM payment the buyer's
2853
+ * wallet sends itself, it signs Quasar's message for free, so that Quasar credits its transfers to this invoice only.
2854
+ * When the checkout asks for it, what it says about a refusal, and which wallets sign with a passkey.
2855
+ */
2856
+
2857
+ /** Why the wallet did not confirm: its kind of failure, or a network switch the buyer refused. */
2858
+ type ConfirmProblem = PaymentWalletErrorKind | 'switchDeclined';
2859
+ /**
2860
+ * Whether the wallet is a smart account that signs with a passkey (or a fingerprint), by its connector type.
2861
+ *
2862
+ * @param wallet - The connected wallet.
2863
+ * @returns `true` for Coinbase Smart Wallet, Base Account and Porto.
2864
+ */
2865
+ declare function isSmartWallet(wallet: Pick<CheckoutWallet, 'connectorType'> | null | undefined): boolean;
2866
+ /**
2867
+ * Whether the wallet confirms the invoice before it pays from the pay step: while the checkout store says it must
2868
+ * (`required`, `confirming`), and for a method the gasless relay could pay (`unless_relayed`) when the wallet sends the
2869
+ * transfer or the paymaster's calls itself; the relay's signed authorization confirms the wallet on its own.
2870
+ *
2871
+ * @param payerProof - `payerProof` of the checkout store (left out by older stores).
2872
+ * @param path - How the wallet pays the quote.
2873
+ * @returns `true` to ask for the confirmation first.
2874
+ */
2875
+ declare function needsPayerProof(payerProof: string | undefined, path: PayPath): boolean;
2876
+ /** The part of the checkout store {@link lockPrice} reads. */
2877
+ interface LockPriceStore {
2878
+ /** The store's state and actions. */
2879
+ getState: () => Pick<CheckoutState, 'requestQuote' | 'error'> & {
2880
+ readonly payerProof?: string;
2881
+ };
2882
+ }
2883
+ /**
2884
+ * Locks the price for the wallet the buyer continued with, or turns to the step that confirms the wallet first: while
2885
+ * the checkout store says the wallet must confirm the invoice (`payerProof` `required`), no price is asked; when Quasar
2886
+ * refuses the price with `payer_proof_required` (a wallet it wants confirmed, which the checkout did not announce), the
2887
+ * step shows too.
2888
+ *
2889
+ * Side effects: `POST quote` through the checkout store.
2890
+ *
2891
+ * @param store - The checkout store.
2892
+ * @param showConfirmWallet - Shows (`true`) or leaves (`false`) the step that confirms the wallet.
2893
+ * @returns The quote, or `null` when none was locked.
2894
+ */
2895
+ declare function lockPrice(store: LockPriceStore, showConfirmWallet: (show: boolean) => void): Promise<CheckoutQuote | null>;
2896
+ /**
2897
+ * Whether the error is a refusal of the wallet's confirmation (`payer_proof_*`, `payer_chain_mismatch`,
2898
+ * `too_many_payers`): the pay step shows only these under the confirmation, its other errors have texts of their own.
2899
+ *
2900
+ * @param error - The checkout store's error, if any.
2901
+ * @returns `true` for a refusal of the confirmation.
2902
+ */
2903
+ declare function isPayerProofError(error: CheckoutError | null | undefined): boolean;
2904
+ /**
2905
+ * Whether an error belongs on the step that confirms the wallet. The store's error may be about something else: a
2906
+ * transfer held from another wallet, or a price refused to the last wallet, opened the step with "Something went wrong"
2907
+ * before the wallet was asked anything.
2908
+ *
2909
+ * @param error - The checkout store's error, if any.
2910
+ * @returns `true` for a refusal of the confirmation or a failure of its requests.
2911
+ */
2912
+ declare function isConfirmationError(error: CheckoutError | null | undefined): boolean;
2913
+ /**
2914
+ * What the step that confirms the wallet says about a refusal, with what to do: the wallet's (the buyer declined, the
2915
+ * wallet cannot sign messages, it failed) or Quasar's (`payer_proof_invalid`, `payer_proof_unavailable`,
2916
+ * `payer_chain_mismatch`, `too_many_payers`, `rate_limited`…). The buyer stays on the step and can try again.
2917
+ *
2918
+ * @param error - The checkout store's error, if any.
2919
+ * @param problem - Why the wallet did not sign, when the checkout knows it.
2920
+ * @param labels - The labels of the checkout language.
2921
+ * @param values - The wallet's name, the method's network and the seller's name.
2922
+ * @param values.wallet - The wallet's name.
2923
+ * @param values.network - The network of the method.
2924
+ * @param values.merchant - The seller's name.
2925
+ * @returns The text, or `null` with nothing to say (no error, or `payer_proof_required`, the reason the step shows).
2926
+ */
2927
+ declare function payerProofErrorText(error: CheckoutError | null | undefined, problem: ConfirmProblem | null, labels: NovaPaymentsLabels, values: {
2928
+ wallet: string;
2929
+ network: string;
2930
+ merchant: string;
2931
+ }): string | null;
1266
2932
 
1267
2933
  /**
1268
2934
  * @file A QR code as one SVG path, so the checkout draws it in its own colors.
@@ -1279,6 +2945,21 @@ declare function qrPath(text: string): {
1279
2945
  path: string;
1280
2946
  };
1281
2947
 
2948
+ /**
2949
+ * @file A refund as the merchant's wallet sends it: the transfer Quasar asks for, in the shape of a payment.
2950
+ */
2951
+
2952
+ /** What Quasar asks the merchant to send for a refund (`instructions` of the refund store). */
2953
+ type RefundInstructions = NonNullable<RefundState['instructions']>;
2954
+ /**
2955
+ * The transfer of a refund as a payments adapter sends it (`sendTransfer`): the asset of the payment to the payer, on
2956
+ * the chain of the payment. The token is the contract or mint of the CAIP-19 asset, `native` for the coin of the chain.
2957
+ *
2958
+ * @param instructions - What Quasar asks to send.
2959
+ * @returns The transfer, or `null` without a recipient or on a chain no adapter pays on.
2960
+ */
2961
+ declare function refundTransfer(instructions: RefundInstructions): PaymentInstructions | null;
2962
+
1282
2963
  /**
1283
2964
  * Subtotal and tax of the invoice from its lines: the lines carry net amounts, the total includes tax. The tax row
1284
2965
  * shows the rate when all taxed lines share one.
@@ -1293,4 +2974,5 @@ declare function invoiceTotals(invoice: CheckoutView['invoice']): {
1293
2974
  total: string;
1294
2975
  };
1295
2976
 
1296
- export { AutoPayScreen, type AutoPayTerms, type BalanceShortfall, type BuyerCollect, type BuyerField, type BuyerIssue, BuyerScreen, CheckoutContext, CheckoutContextProvider, type CheckoutContextValue, CheckoutHeader, type CheckoutHeaderProps, type CheckoutScreen, type CheckoutScreenChoices, type CheckoutStep, CheckoutStepper, type CheckoutStepperProps, CheckoutSummary, type CheckoutTokenGroup, CheckoutWallet, CompactSummary, ConfirmScreen, DEADLINE_ANNOUNCEMENTS, DeadlineTimer, type HandOverParams, LeaveDialog, LocaleSwitcher, type LocaleSwitcherProps, MerchantBadge, MethodScreen, MobileSteps, NovaPaymentsContext, type NovaPaymentsLabelsContext, NovaPaymentsProvider, type NovaPaymentsProviderCustomization, type NovaPaymentsProviderProps, type NovaPaymentsSettings, OrderLines, OrderTotal, type OutcomeKind, OutcomeScreen, PaidScreen, type PayInvoiceParams, type PayPath, PayScreen, type Payment, PaymentCheckout, type PaymentCheckoutDisplay, type PaymentCheckoutProps, PaymentFamily, type PaymentStatus, PaymentWalletError, type PaymentWalletErrorKind, PaymentsAdapter, type PaymentsPulsar, QUOTE_WARNING_MS, QrScreen, type QuoteAmounts, SellerDetailsContent, type SentPayment, SummaryFooter, type UseAutoReturnParams, type UseCheckoutStoreOptions, type UsePaymentHandOverParams, type UsePaymentParams, type WalletConnection, WalletPrompt, type WalletPromptKind, type WalletPromptProps, autoPayTerms, balanceShortfall, baseUnitsToDecimal, buyerFields, buyerIssues, checkoutScreen, checkoutSteps, cleanBuyer, contactHref, countryOptions, deadlineAnnouncement, formatCountdown, formatFiat, formatPeriod, formatTokenAmount, groupMethodsByToken, handOverPayment, instructionsChainId, invoiceTotals, isQuoteEnding, methodErrorText, minorToDecimal, needsLeaveConfirm, payInvoice, payPath, qrPath, quoteAmounts, quoteRate, shortAddress, shouldHandOver, underpaidRest, useAsyncValue, useAutoReturn, useCheckoutContext, useCheckoutState, useCheckoutStore, useConnectedWallet, useNovaPayments, useNow, usePaidCallback, usePayment, usePaymentFacts, usePaymentHandOver, usePaymentsLabels, useWalletConnection, walletErrorKind };
2977
+ export { AmountStep, AutoPayScreen, BuyerScreen, CheckoutContext, CheckoutContextProvider, CheckoutFrame, CheckoutHeader, CheckoutPageRoot, CheckoutStepper, CheckoutSummary, CheckoutWallet, CompactSummary, ConfirmScreen, ConfirmStep, ConfirmWalletScreen, DEADLINE_ANNOUNCEMENTS, DeadlineTimer, Disclosure, FailedStep, LeaveDialog, LocaleSwitcher, MerchantBadge, MethodScreen, MobileSteps, NativeFee, NovaPaymentsContext, NovaPaymentsProvider, OPEN_REQUEST_MS, OrderLines, OrderTotal, OutcomeScreen, PaidScreen, PayScreen, PaymentCheckout, PaymentFamily, PaymentWalletError, PaymentsAdapter, QUOTE_WARNING_MS, QrScreen, RefundButton, RefundDialog, RefundSteps, ScreenBody, SellerDetailsContent, SummaryFooter, WalletPrompt, addressOfWallet, autoPayTerms, balanceShortfall, baseUnitsToDecimal, buyerFields, buyerIssues, checkoutClassName, checkoutScreen, checkoutSteps, cleanBuyer, contactHref, countryOptions, deadlineAnnouncement, deadlineState, formatCountdown, formatFeeAmount, formatFiat, formatPeriod, formatTokenAmount, grantableOffer, groupMethodsByToken, handOverPayment, instructionsChainId, invoiceTotals, isConfirmationError, isFinalPaymentFailure, isInvoicePaymentOnTheWay, isInvoicePaymentUnresolved, isMovedMoneyFailure, isPaidElsewhere, isPayerProofError, isPaymentAccepted, isPaymentOnTheWay, isQuoteEnding, isSameWallet, isSlow, isSmartWallet, leftTheWalletText, lockPrice, lockedPriceOnWallet, methodErrorText, minorToDecimal, needsLeaveConfirm, needsPayerProof, needsTheClock, paidSteps, payInvoice, payPath, payerProofErrorText, qrPath, quoteAmounts, quoteRate, receivedAmount, refundRateMoved, refundTransfer, refusalText, restRateText, screensPayingWallets, sentBeforeDeadline, shouldHandOver, takeOverOpens, unconfirmedFollowUp, unconfirmedTxKey, underpaidRest, useAsyncValue, useAutoReturn, useCheckoutContext, useCheckoutEvents, useCheckoutState, useCheckoutStore, useConnectedWallet, useNovaPayments, useNow, useOptionalCheckoutContext, usePaidCallback, usePayerProof, usePayment, usePaymentFacts, usePaymentHandOver, usePaymentsConnection, usePaymentsLabels, useRefund, useRereadValue, useWalletConnection, walletErrorKind, walletOnConfirmStep };
2978
+ export type { AutoPayTerms, BalanceShortfall, BuyerCollect, BuyerField, BuyerIssue, CheckoutContextValue, CheckoutHeaderProps, CheckoutNetworkOptionProps, CheckoutPartState, CheckoutPrimaryButtonProps, CheckoutQrCodeProps, CheckoutScreen, CheckoutScreenChoices, CheckoutScreenProps, CheckoutStatusIconProps, CheckoutStep, CheckoutStepperProps, CheckoutTokenGroup, CheckoutTokenOptionProps, ConfirmProblem, HandOverParams, LocaleSwitcherProps, LockPriceStore, NovaPaymentsLabelsContext, NovaPaymentsOwnConnection, NovaPaymentsProviderCustomization, NovaPaymentsProviderProps, NovaPaymentsSettings, OutcomeKind, PayInvoiceParams, PayPath, PayerProofFlow, PayerProofProblem, PayerProofStep, Payment, PaymentCheckoutChildCustomizations, PaymentCheckoutClassNames, PaymentCheckoutComponents, PaymentCheckoutConfig, PaymentCheckoutCustomization, PaymentCheckoutDisplay, PaymentCheckoutHandlers, PaymentCheckoutProps, PaymentStatus, PaymentWalletErrorKind, PaymentsConnectionMode, PaymentsPulsar, QuoteAmounts, RefundButtonProps, RefundDialogProps, RefundFlow, RefundInstructions, RefundProblem, RefundRequest, RefundStep, SentBeforeDeadlineParams, SentPayment, UnconfirmedFollowUp, UseAutoReturnParams, UseCheckoutEventsParams, UseCheckoutStoreOptions, UsePayerProofParams, UsePaymentHandOverParams, UsePaymentParams, UseRefundParams, WalletConnection, WalletPromptKind, WalletPromptProps };