@tuwaio/nova-payments 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +139 -12
  2. package/dist/OwnConnection-ET76SUMX.js +1 -0
  3. package/dist/OwnConnection-S5SQLIBT.cjs +1 -0
  4. package/dist/chunk-7FQXTBOY.cjs +1 -0
  5. package/dist/chunk-7HSDAUKN.js +1 -0
  6. package/dist/chunk-EMYW4LI7.js +1 -0
  7. package/dist/chunk-HRTXVGBJ.cjs +1 -0
  8. package/dist/de-DXFDX3GR.js +1 -0
  9. package/dist/de-TJ6BGSUG.cjs +1 -0
  10. package/dist/es-DCARFZ3R.js +1 -0
  11. package/dist/es-I4V64VEP.cjs +1 -0
  12. package/dist/evm/index.cjs +1 -1
  13. package/dist/evm/index.d.cts +14 -6
  14. package/dist/evm/index.d.ts +14 -6
  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 +626 -61
  22. package/dist/index.d.cts +2181 -373
  23. package/dist/index.d.ts +2181 -373
  24. package/dist/index.js +2 -1
  25. package/dist/it-N36S2FXH.js +1 -0
  26. package/dist/it-RQJGHQPP.cjs +1 -0
  27. package/dist/locales-DP2jStIs.d.cts +1282 -0
  28. package/dist/locales-DP2jStIs.d.ts +1282 -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-FFP4RBO4.js +1 -0
  36. package/dist/uk-HYM26VN5.cjs +1 -0
  37. package/dist/zhCN-EKUFCQTZ.js +1 -0
  38. package/dist/zhCN-Q5DO4HXO.cjs +1 -0
  39. package/package.json +39 -39
  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,54 @@ 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), a payment that
54
+ * failed for good while the invoice still takes one (`failed`: the buyer may pay again) or its outcome.
40
55
  */
41
- type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'pay' | 'qr' | 'confirm' | 'paid' | 'autoPay' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked';
56
+ type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'confirmWallet' | 'pay' | 'qr' | 'confirm' | 'unconfirmed' | 'failed' | 'paid' | 'autoPay' | 'autoPayOff' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked';
42
57
  /** Choices of the buyer that the checkout store does not hold. */
43
58
  interface CheckoutScreenChoices {
44
59
  /** Pay from a wallet in this browser (default) or scan a QR code with a phone. */
45
60
  payWith?: 'wallet' | 'qr';
46
61
  /** The buyer opened the automatic payments offer after paying the first period of a subscription. */
47
62
  autoPay?: boolean;
63
+ /** The buyer opened the screen that turns automatic payments off, while they are on. */
64
+ autoPayOff?: boolean;
48
65
  /**
49
66
  * The buyer continues on a phone: with `payWith` `qr`, the QR code of the payment page shows before any price is
50
67
  * locked (an EVM method, paid from the phone's wallet on that page).
51
68
  */
52
69
  handoff?: boolean;
70
+ /**
71
+ * The labels of the invoice's language are loaded (default `true`). Until then the checkout stays on `loading`, so
72
+ * its first screen never shows in English before the buyer's language arrives.
73
+ */
74
+ labelsReady?: boolean;
75
+ /**
76
+ * The buyer continued with a wallet that must confirm the invoice before the price (`payerProof` of the checkout
77
+ * store is `required`): the step that confirms it shows while the store waits for the signature and locks the price
78
+ * after it.
79
+ */
80
+ confirmWallet?: boolean;
81
+ /**
82
+ * A payment this page followed has just failed for good, and the buyer has not gone on yet: the `failed` step shows
83
+ * what became of it, in place of the step the store went back to, until the buyer chooses to pay again.
84
+ */
85
+ afterFailure?: boolean;
53
86
  }
87
+ /**
88
+ * Whether the permission screen can open from this phase: another wallet takes over a permission from the steps before a
89
+ * payment, not from an outcome that keeps its own screen.
90
+ *
91
+ * @param phase - The phase of the checkout store.
92
+ * @returns Whether "Use this wallet" leads somewhere.
93
+ */
94
+ declare const takeOverOpens: (phase: string | undefined) => boolean;
54
95
  /**
55
96
  * The screen for the state of a checkout store.
56
97
  *
@@ -58,16 +99,27 @@ interface CheckoutScreenChoices {
58
99
  * @param state.phase - Where the payment stands.
59
100
  * @param state.checkout - What the checkout token opens; `null` until loaded.
60
101
  * @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.
102
+ * busy, so a refused payer or a failed request is shown where the buyer chose (the step that confirms the wallet, when
103
+ * the price is locked after it).
104
+ * @param state.payerProof - Whether the connected wallet must confirm the invoice (`payerProof` of the checkout store;
105
+ * left out by older stores).
106
+ * @param state.error - The store's last error: a price refused after the signature shows on the method step.
62
107
  * @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.
108
+ * @returns The screen: `confirmWallet` once the buyer continued (`choices.confirmWallet`) while the wallet must
109
+ * confirm the invoice or confirms it, and after it until the price is locked (unless it was refused), also on an
110
+ * underpaid invoice whose rest another wallet pays, `qr` instead of `pay` when the buyer pays
111
+ * with a QR code (or the price was locked without a payer), `replaced` for an invoice the seller
112
+ * corrected, `autoPay` after a paid subscription period while the automatic payments offer is open, `loading` until
113
+ * the labels of the invoice's language are loaded, `unconfirmed` in the phase of that name of a current
114
+ * `@tuwaio/quasar-sdk` (Quasar could not confirm the payment, which may still arrive). While the store hands a transaction
115
+ * over again (`submit_retrying`) it is `confirm`: only Quasar is out of reach, and the payment goes on.
66
116
  */
67
117
  declare function checkoutScreen(state: {
68
118
  phase: CheckoutPhase;
69
119
  checkout: CheckoutView | null;
70
120
  quote?: CheckoutQuote | null;
121
+ readonly payerProof?: string;
122
+ error?: CheckoutError | null;
71
123
  }, choices?: CheckoutScreenChoices): CheckoutScreen;
72
124
  /** A step of the stepper in the checkout header. */
73
125
  interface CheckoutStep {
@@ -87,6 +139,17 @@ interface CheckoutStep {
87
139
  declare function checkoutSteps(screen: CheckoutScreen, options?: {
88
140
  withDetails?: boolean;
89
141
  }): CheckoutStep[] | null;
142
+ /**
143
+ * The steps of the stepper on the paid screen, all done: the row stays as the payment confirms ({@link checkoutSteps}
144
+ * gives none for an outcome).
145
+ *
146
+ * @param options - Steps that apply to this invoice.
147
+ * @param options.withDetails - The checkout asked for the buyer details first.
148
+ * @returns The steps.
149
+ */
150
+ declare function paidSteps(options?: {
151
+ withDetails?: boolean;
152
+ }): CheckoutStep[];
90
153
  /** The methods of one token, as the method step shows it: the token first, then its network. */
91
154
  interface CheckoutTokenGroup {
92
155
  /** Token symbol. */
@@ -99,7 +162,7 @@ interface CheckoutTokenGroup {
99
162
  inWallet: boolean;
100
163
  }
101
164
  /**
102
- * Groups payment methods by token: the token picked first, then its network (decision of 2026-10-10). Groups with a
165
+ * Groups payment methods by token: the token picked first, then its network. Groups with a
103
166
  * method on the connected wallet's network come first, then those the merchant marks Popular; otherwise the
104
167
  * merchant's order stays.
105
168
  *
@@ -108,19 +171,76 @@ interface CheckoutTokenGroup {
108
171
  * @returns The groups.
109
172
  */
110
173
  declare function groupMethodsByToken(methods: CheckoutMethod[], walletChainId?: string | null): CheckoutTokenGroup[];
174
+ /**
175
+ * Where the invoice deadline stands for the checkout: the countdown shows through every step of the payment, also while
176
+ * the wallet signs, the payment is handed to Quasar and it confirms, and on a payer the wallet check refused
177
+ * (`blocked`, where the buyer can pay with another wallet); it ends with the paid outcome and with the outcomes in which
178
+ * a deadline means nothing. A payment sent before the deadline counts: Quasar keeps an `open` or `underpaid` invoice
179
+ * while a payment it learned of before the deadline confirms (for a limited time), and holds a payment that lands after
180
+ * the invoice closed for the seller to accept or return.
181
+ *
182
+ * @param status - The invoice state (`checkout.invoice.status`).
183
+ * @param screen - The screen shown.
184
+ * @param restPayable - Whether the rest of an underpaid invoice can be paid (`invoice.restPayable`).
185
+ * @returns `paying` while the buyer can still pay (the countdown shows and screen readers hear the minutes left),
186
+ * `confirming` while the payment is on its way (the countdown shows; at zero the confirm step says that the payment
187
+ * sent in time is being confirmed) and while Quasar could not confirm it (`unconfirmed`: the buyer checks the wallet
188
+ * before paying again, so no minutes left to pay are announced), or `null` once the payment succeeded (`paid`,
189
+ * `autoPay`), on the outcomes in
190
+ * which a deadline means nothing (`held`, `refunded`, `expired`, `cancelled`, `replaced`) and for an invoice that can
191
+ * no longer be paid. `closed` while part of an underpaid invoice arrived and its rest cannot be paid: the countdown still
192
+ * shows, as the time after which the seller can refund, and no minutes left to pay are announced.
193
+ */
194
+ declare function deadlineState(status: string, screen: CheckoutScreen, restPayable?: boolean): 'paying' | 'confirming' | 'closed' | null;
111
195
  /** Minutes before the invoice deadline at which screen readers hear how much time is left. */
112
196
  declare const DEADLINE_ANNOUNCEMENTS: readonly [10, 5, 1];
113
197
  /**
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.
198
+ * Whether a tick of the invoice countdown crossed one of the announcement minutes ({@link DEADLINE_ANNOUNCEMENTS} by
199
+ * default): the checkout announces the time left then (WCAG 2.2.1), not every second.
116
200
  *
117
201
  * @param previousMs - Time left at the previous tick; `null` on the first one.
118
202
  * @param ms - Time left now.
203
+ * @param announcements - The minutes before the deadline to announce at.
119
204
  * @returns The minutes to announce (the nearest when several were crossed at once), or `null`.
120
205
  */
121
- declare function deadlineAnnouncement(previousMs: number | null, ms: number): number | null;
206
+ declare function deadlineAnnouncement(previousMs: number | null, ms: number, announcements?: readonly number[]): number | null;
122
207
  /** How long before a locked price ends the checkout offers to keep it (WCAG 2.2.1: 20 seconds at least). */
123
208
  declare const QUOTE_WARNING_MS = 60000;
209
+ /**
210
+ * What the active wallet changing does to a locked price. A wallet connected to turn automatic payments off pays
211
+ * nothing, so it changes nothing while that screen is open; back on the payment, what follows applies.
212
+ *
213
+ * @param params - What the change happens over.
214
+ * @param params.autoPayOffOpen - The screen that turns automatic payments off is open.
215
+ * @param params.phase - The phase of the payment; a price is locked only in `awaitingPayment`.
216
+ * @param params.quotePayer - The payer the price is locked for.
217
+ * @param params.payer - The payer the active wallet gives for the method of that price, or `null`.
218
+ * @returns `keep`: nothing changes; `lock`: lock the price again for `payer`; `release`: release it, back to the methods.
219
+ */
220
+ declare function lockedPriceOnWallet(params: {
221
+ autoPayOffOpen: boolean;
222
+ phase: string;
223
+ quotePayer: string | null | undefined;
224
+ payer: string | null;
225
+ }): 'keep' | 'lock' | 'release';
226
+ /**
227
+ * What the active wallet changing does on the step that confirms the wallet, where no new price is locked yet: the step
228
+ * asks the wallet connected to sign, never the one the store last held.
229
+ *
230
+ * @param params - What the change happens over.
231
+ * @param params.open - The step shows.
232
+ * @param params.storePayer - The payer the store holds, which the step would ask to sign for.
233
+ * @param params.payer - The payer the active wallet gives for the chosen method, or `null`.
234
+ * @param params.paysRest - That wallet may pay: only the first wallet pays the rest of an underpaid invoice.
235
+ * @returns `keep`: nothing changes; `follow`: this wallet signs, or goes on to the price if it confirmed already; `leave`:
236
+ * the step closes, with no wallet to ask.
237
+ */
238
+ declare function walletOnConfirmStep(params: {
239
+ open: boolean;
240
+ storePayer: string | null;
241
+ payer: string | null;
242
+ paysRest: boolean;
243
+ }): 'keep' | 'follow' | 'leave';
124
244
  /**
125
245
  * Whether a locked price is in its last minute, when the checkout offers to keep it.
126
246
  *
@@ -128,13 +248,194 @@ declare const QUOTE_WARNING_MS = 60000;
128
248
  * @returns `true` from {@link QUOTE_WARNING_MS} down to the end.
129
249
  */
130
250
  declare function isQuoteEnding(ms: number): boolean;
251
+ /**
252
+ * Whether the merchant checks paying wallets before payment: `amlScreening` of the checkout, `true` when its AML mode
253
+ * is `block` or `flag`. The pay step says so only then. A checkout of a Quasar version without the field counts as
254
+ * checking, as the pay step always said before.
255
+ *
256
+ * @param checkout - What the checkout token opens.
257
+ * @returns `false` only when the checkout says that the merchant does not check paying wallets.
258
+ */
259
+ declare function screensPayingWallets(checkout: CheckoutView): boolean;
260
+ /**
261
+ * Whether a payment this page handed over is on its way: `paymentOnTheWay` of the checkout store of a current
262
+ * `@tuwaio/quasar-sdk` (`true` from a successful submit or relay, also a relay answered `sending`, which has no
263
+ * transaction key, until the payment settles or fails), else, with an older store without the field, whether the page
264
+ * handed over a transaction (`txKey` or `txHash`).
265
+ *
266
+ * @param state - The state of the checkout store.
267
+ * @param state.paymentOnTheWay - What the store says, when it has the field.
268
+ * @param state.txKey - The transaction this page submitted.
269
+ * @param state.txHash - The transaction of the payment, once known.
270
+ * @param state.error - The store's error, which names a transaction of its own when its nonce is unexplained.
271
+ * @returns Whether a payment of this page may still arrive.
272
+ */
273
+ declare function isPaymentOnTheWay(state: Pick<CheckoutState, 'txKey' | 'txHash'> & {
274
+ readonly paymentOnTheWay?: boolean;
275
+ }): boolean;
276
+ /**
277
+ * Whether Quasar reports a payment of the invoice on its way, whoever handed it over (another tab, the page before it
278
+ * was reloaded, a Solana Pay transfer Quasar found): `invoicePaymentOnTheWay` of the checkout store of a current
279
+ * `@tuwaio/quasar-sdk`, else, with an older store without the field, the `pendingPayments` of the checkout it read.
280
+ *
281
+ * @param state - The state of the checkout store.
282
+ * @param state.invoicePaymentOnTheWay - What the store says, when it has the field.
283
+ * @param checkout - What the checkout token opens; `null` until loaded.
284
+ * @returns Whether a payment of the invoice may still arrive.
285
+ */
286
+ declare function isInvoicePaymentOnTheWay(state: object & {
287
+ readonly invoicePaymentOnTheWay?: boolean;
288
+ }, checkout: CheckoutView | null): boolean;
289
+ /** What {@link sentBeforeDeadline} decides with. */
290
+ interface SentBeforeDeadlineParams {
291
+ /**
292
+ * The state of the checkout store: `paymentCountsUntil`, `paymentSentInTime` and `paymentOnTheWay` of a current
293
+ * `@tuwaio/quasar-sdk` (`txKey`/`txHash` with an older one).
294
+ */
295
+ state: object & {
296
+ readonly paymentCountsUntil?: string | null;
297
+ readonly paymentSentInTime?: boolean | null;
298
+ readonly paymentOnTheWay?: boolean;
299
+ readonly txKey?: string | null;
300
+ readonly txHash?: string | null;
301
+ };
302
+ /** The checkout: its invoice's `paymentCountsUntil` tells whether Quasar reports it, and is read with an older store. */
303
+ checkout: CheckoutView;
304
+ /** When this page handed its payment over, by its clock; `null` when it does not know (a reload, another tab). */
305
+ handedOverAt: number | null;
306
+ /** The invoice deadline (`dueAt`) in milliseconds. */
307
+ dueAt: number;
308
+ }
309
+ /**
310
+ * Whether the payment on its way counts as sent before the invoice deadline. For a payment this page handed over that
311
+ * Quasar already reported on, Quasar's word on that payment decides (`paymentSentInTime` of the checkout store: its keys
312
+ * are among the `onTimeTxKeys` Quasar learned of before `dueAt`), whatever the clock of the page says. Otherwise Quasar
313
+ * says it for the invoice with `paymentCountsUntil` (it learned of a payment of the invoice before `dueAt` and waits for
314
+ * it): its word decides, except for a payment this page handed over at or after the deadline by its clock, which Quasar
315
+ * holds even while it waits for another one. A Quasar that does not report the field leaves the clock of the page: a
316
+ * payment this page handed over before the deadline.
317
+ *
318
+ * @param params - See {@link SentBeforeDeadlineParams}.
319
+ * @returns `true` to say that the payment was sent in time and is being confirmed.
320
+ */
321
+ declare function sentBeforeDeadline({ state, checkout, handedOverAt, dueAt }: SentBeforeDeadlineParams): boolean;
322
+ /**
323
+ * Whether the last error says that the payment can never pay the invoice: `payment_failed` (reverted, cancelled…) or
324
+ * `payment_mismatch` (it does not pay the invoice: a wrong amount or recipient…), with the reason Quasar gave. A failure
325
+ * without a reason comes from a Quasar or a `@tuwaio/quasar-sdk` that cannot tell a final failure from a payment that
326
+ * may still arrive, so it does not count, nor does `settlement_failed` (a payment the network confirmed that Quasar has
327
+ * not recorded yet, which an older store reports as `payment_mismatch`).
328
+ *
329
+ * @param error - The store's error.
330
+ * @returns `true` when the payment failed for good.
331
+ */
332
+ declare function isFinalPaymentFailure(error: CheckoutError | null | undefined): boolean;
333
+ /**
334
+ * Whether the last error says that the transaction succeeded on chain but does not pay the invoice (a wrong amount,
335
+ * asset or recipient, no Solana Pay reference, sent before the price was locked…): `payment_mismatch` of a current
336
+ * `@tuwaio/quasar-sdk`, or `payment_failed` with such a reason from an older one. It may have moved money, so the
337
+ * checkout never says that it did not go through or that nothing was charged: it says that the transaction does not pay
338
+ * the invoice, and to contact the seller if money left the wallet. A payment the network confirmed that Quasar has not
339
+ * recorded yet (`settlement_failed`, which an older store reports as `payment_mismatch`) is not one: it pays the
340
+ * invoice once Quasar records it.
341
+ *
342
+ * @param error - The store's error.
343
+ * @returns `true` for a transaction that does not pay the invoice.
344
+ */
345
+ declare function isMovedMoneyFailure(error: CheckoutError | null | undefined): boolean;
346
+ /**
347
+ * Whether the last error says that Quasar credited the transaction to another invoice of the seller, the one the
348
+ * wallet that sent it confirmed or whose mark it carries (`tx_already_used` of a transaction that does not pay this
349
+ * invoice): the buyer names it to the seller if it was the payment of this invoice.
350
+ *
351
+ * @param error - The store's error.
352
+ * @returns `true` for a transaction that pays another invoice.
353
+ */
354
+ declare function isPaidElsewhere(error: CheckoutError | null | undefined): boolean;
355
+ /**
356
+ * Whether Quasar reports a payment of the invoice that may still arrive, with no time limit (one stuck past the minutes
357
+ * `pendingPayments` counts, or one whose result Quasar did not see and reads again for 24 hours):
358
+ * `invoicePaymentUnresolved` of the checkout store of a current `@tuwaio/quasar-sdk`, else the `unresolvedPayments` of
359
+ * the checkout it read. While it is `true` the checkout never says that nothing was charged.
360
+ *
361
+ * @param state - The state of the checkout store.
362
+ * @param state.invoicePaymentUnresolved - What the store says, when it has the field.
363
+ * @param checkout - What the checkout token opens; `null` until loaded.
364
+ * @returns Whether a payment of the invoice may still arrive.
365
+ */
366
+ declare function isInvoicePaymentUnresolved(state: object & {
367
+ readonly invoicePaymentUnresolved?: boolean;
368
+ }, checkout: CheckoutView | null): boolean;
369
+ /**
370
+ * What the checkout tells the buyer about a payment that may have left the wallet and that Quasar did not confirm:
371
+ * `rechecked` (Quasar still reads it again, for up to 24 hours after it learned of it, and records it for the seller if
372
+ * it arrives), `retrying` (the checkout store keeps handing over a transaction the wallet sent, which Quasar has not
373
+ * received yet: keep the page open), `notReceived` (the store gave up handing it over after an hour: Quasar never
374
+ * received it), `contact` (a reason Quasar never reads again: a relay operation lost, `transaction_failed`, a Quasar
375
+ * or a store that does not say), `closed` (Quasar saw no result on chain within 24 hours and closed it),
376
+ * `takenElsewhere` (the page of another invoice handed the transaction over first: Quasar credits it to the invoice
377
+ * that the wallet that sent it confirmed, and the page shows the result while it follows the payment),
378
+ * `settlementRetrying` (the network confirmed it, but Quasar has not recorded it yet and settles it again daily, for 30
379
+ * days after it learned of it: `rechecked`), `settlementFailed` (the same, without Quasar saying that it still
380
+ * 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
381
+ * `takenElsewhere`, `settlementRetrying` and `settlementFailed` the payment left the wallet, so the checkout offers no
382
+ * payment.
383
+ */
384
+ type UnconfirmedFollowUp = 'nonceSpent' | 'unmined' | 'rechecked' | 'retrying' | 'notReceived' | 'contact' | 'closed' | 'takenElsewhere' | 'settlementRetrying' | 'settlementFailed' | 'invoiceFull';
385
+ /**
386
+ * What to tell the buyer about a payment Quasar did not confirm, from the store's error: `payment_unconfirmed` with
387
+ * `rechecked` (set by a current `@tuwaio/quasar-sdk` only while Quasar reads the payment again) promises the 24-hour
388
+ * re-check, its `submit_retrying` and `submit_failed` reasons are the store's hand-over, `tx_already_used` a transaction
389
+ * another invoice handed over first, any other is for the seller; `payment_failed` with the reason
390
+ * `unresolved_after_24h` is a payment Quasar closed without a result; the reason `settlement_failed` (`payment_mismatch`
391
+ * of an older store) a confirmed payment Quasar has not recorded yet, which Quasar settles again daily only while
392
+ * `rechecked` (for 30 days after it learned of it).
393
+ *
394
+ * @param error - The store's error.
395
+ * @returns See {@link UnconfirmedFollowUp}; `null` for any other error, or none.
396
+ */
397
+ declare function unconfirmedFollowUp(error: CheckoutError | null | undefined): UnconfirmedFollowUp | null;
398
+ /**
399
+ * The transaction the buyer names to the seller about a payment Quasar did not confirm: the one this page handed over
400
+ * (`txHash`, else `txKey` of the checkout store), else, on a reopened page, the newest one Quasar rejected.
401
+ *
402
+ * @param state - The state of the checkout store.
403
+ * @param state.txKey - The transaction this page submitted.
404
+ * @param state.txHash - The transaction of the payment, once known.
405
+ * @param checkout - What the checkout token opens; `null` until loaded.
406
+ * @returns The transaction hash (EVM) or signature (Solana), or `null` when the page does not know it.
407
+ */
408
+ declare function unconfirmedTxKey(state: Pick<CheckoutState, 'txKey' | 'txHash'> & {
409
+ error?: object | null;
410
+ }, checkout: CheckoutView | null): string | null;
411
+ /**
412
+ * The language a checkout shows. The buyer's pick in the language menu comes first, as long as the page around the
413
+ * checkout still has the language it had then: a page that changes its language is followed again. Then the language of
414
+ * that page (`locale` of `PaymentCheckout`), then the language of the invoice, then English.
415
+ *
416
+ * @param params - What is known.
417
+ * @param params.picked - The language the buyer picked in the menu during this visit, with the language the page had
418
+ * then; `null` before a pick.
419
+ * @param params.page - The language of the page around the checkout, as a language of the checkout; `null` when the
420
+ * app gave none or the checkout does not have it.
421
+ * @param params.invoice - The language of the invoice; `null` before the invoice is read.
422
+ * @returns The language, a BCP 47 tag.
423
+ */
424
+ declare function shownLocale({ picked, page, invoice, }: {
425
+ picked: {
426
+ locale: string;
427
+ page: string | null;
428
+ } | null;
429
+ page: string | null;
430
+ invoice: string | null | undefined;
431
+ }): string;
131
432
 
132
433
  /**
133
- * @file Handing a payment the wallet sent over to the app's Pulsar store when the checkout closes before Quasar
134
- * settled it: Pulsar keeps tracking it, and Nova Transactions shows its toast.
434
+ * @file Handing a payment of a checkout over to the app's Pulsar store: Pulsar tracks it and keeps it in the history,
435
+ * and Nova Transactions shows its toast.
135
436
  */
136
437
 
137
- /** A payment the wallet sent, as the checkout remembers it until Quasar settles it. */
438
+ /** A payment of the checkout: one the wallet sent, or one Quasar found and recorded. */
138
439
  interface SentPayment {
139
440
  /** The transaction hash (EVM) or signature (Solana). */
140
441
  txKey: string;
@@ -158,19 +459,6 @@ interface PaymentsPulsar {
158
459
  */
159
460
  injectExternalPendingTxs(transactions: Transaction[]): Promise<void>;
160
461
  }
161
- /**
162
- * Whether a sent payment still needs tracking when the checkout closes: Quasar has not settled it, and it did not
163
- * fail on-chain.
164
- *
165
- * @param state - The `phase` and `error` of the checkout store.
166
- * @param state.phase - Where the payment stands.
167
- * @param state.error - The last failure; `payment_failed` means the transaction failed on-chain.
168
- * @returns `true` to hand it over.
169
- */
170
- declare function shouldHandOver(state: {
171
- phase: CheckoutPhase;
172
- error: CheckoutError | null;
173
- }): boolean;
174
462
  /** What {@link handOverPayment} needs. */
175
463
  interface HandOverParams {
176
464
  /** The adapter of the payment's chain family. */
@@ -204,90 +492,6 @@ interface HandOverParams {
204
492
  */
205
493
  declare function handOverPayment({ adapter, pulsar, payment, labels, merchant, invoice, amount, }: HandOverParams): Promise<boolean>;
206
494
 
207
- /** What the parts of a checkout share: its store and state, the screen, the language and its labels. */
208
- interface CheckoutContextValue {
209
- /** The checkout store of the invoice. */
210
- store: CheckoutStore;
211
- /** The state of the store. */
212
- state: CheckoutState;
213
- /** The checkout, once loaded. */
214
- checkout: CheckoutView | null;
215
- /** The screen shown. */
216
- screen: CheckoutScreen;
217
- /** The language of the checkout (a BCP 47 tag). */
218
- locale: string;
219
- /** The labels of that language. */
220
- labels: NovaPaymentsLabels;
221
- /** `Date.now()` of the latest second tick. */
222
- now: number;
223
- /** Closes the checkout; `undefined` when it cannot be closed (inline without `onClose`). */
224
- close?: () => void;
225
- /** The wallet connected through Satellite Connect, if any. */
226
- wallet: CheckoutWallet | null;
227
- /** How the buyer pays: from a wallet in this browser, or with a QR code on a phone. */
228
- payWith: 'wallet' | 'qr';
229
- /**
230
- * Sets how the buyer pays.
231
- *
232
- * @param payWith - `wallet` or `qr`.
233
- */
234
- 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;
237
- /**
238
- * Asks the buyer to connect a wallet of the method's chain family; the price is locked for it once connected.
239
- *
240
- * @param method - The chosen method.
241
- * @returns Whether the page can connect a wallet (Nova Connect or the app's handler).
242
- */
243
- connectWallet: (method: CheckoutMethod) => boolean;
244
- /**
245
- * The adapter that pays a chain family from the connected wallet.
246
- *
247
- * @param family - The family.
248
- * @returns The adapter of `NovaPaymentsProvider`, if any.
249
- */
250
- adapterFor: (family: PaymentFamily) => PaymentsAdapter | undefined;
251
- /** The buyer continues on a phone: the QR code of the payment page shows before any price. */
252
- handoff: boolean;
253
- /**
254
- * Shows or hides the QR code of the payment page.
255
- *
256
- * @param handoff - Whether it shows.
257
- */
258
- setHandoff: (handoff: boolean) => void;
259
- /** Goes back to the method step: forgets the locked price and the phone hand-off. */
260
- backToMethods: () => void;
261
- /**
262
- * Remembers the payment the wallet sent: the checkout tracks it while open, and hands it over to the app's Pulsar
263
- * store when it closes before Quasar settled it.
264
- *
265
- * @param payment - The transaction and what it pays.
266
- */
267
- onPaymentSent: (payment: SentPayment) => void;
268
- /** The buyer opened the automatic payments offer after paying a subscription period. */
269
- autoPay: boolean;
270
- /**
271
- * Opens or closes the automatic payments offer.
272
- *
273
- * @param autoPay - Whether it shows.
274
- */
275
- setAutoPay: (autoPay: boolean) => void;
276
- /**
277
- * Opens another invoice in this checkout: the one that replaced a corrected invoice.
278
- *
279
- * @param token - Its checkout token.
280
- */
281
- openInvoice: (token: string) => void;
282
- /** Replaces the link of "Contact <seller>", when the app handles it. */
283
- onContact?: () => void;
284
- /** Seconds before the paid outcome sends the buyer back to the seller; `0` for no automatic return. */
285
- autoReturnSeconds: number;
286
- }
287
- declare const CheckoutContext: react.Context<CheckoutContextValue | null>;
288
- /** Gives the parts of a checkout what they share. @internal */
289
- declare const CheckoutContextProvider: react.Provider<CheckoutContextValue | null>;
290
-
291
495
  /** Props of {@link CheckoutHeader}. */
292
496
  interface CheckoutHeaderProps {
293
497
  /** The heading of an outcome screen, shown instead of the steps. */
@@ -317,121 +521,53 @@ interface CheckoutStepperProps {
317
521
  labels: NovaPaymentsLabels;
318
522
  /** Classes added to the list. */
319
523
  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
- /** The merchant's logo (or the first letter of its name), name and website, and the test badge. @internal */
331
- declare function MerchantBadge({ compact }: {
332
- compact?: boolean;
333
- }): react.JSX.Element | null;
334
- /** The seller as the invoice document names them, the merchant's policies and what Quasar is. @internal */
335
- declare function SellerDetailsContent({ checkout, labels }: {
336
- checkout: CheckoutView;
337
- labels: NovaPaymentsLabels;
338
- }): react.JSX.Element;
339
- /** The countdown to the invoice deadline, while the invoice can be paid. @internal */
340
- declare function DeadlineTimer(): react.JSX.Element | null;
341
- /** The lines, subtotal and tax of the invoice. @internal */
342
- declare function OrderLines(): react.JSX.Element | null;
343
- /** The total of the invoice, which stays in place while the lines scroll. @internal */
344
- declare function OrderTotal(): react.JSX.Element | null;
345
- /** "Secured by Quasar" and the seller's support email, at the same place on every step (WCAG 3.2.6). @internal */
346
- declare function SummaryFooter(): react.JSX.Element;
347
- /**
348
- * 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.
350
- *
351
- * @returns The order panel.
352
- */
353
- declare function CheckoutSummary(): react.JSX.Element | null;
354
- /**
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.
357
- *
358
- * @returns The compact order.
359
- */
360
- declare function CompactSummary(): react.JSX.Element | null;
361
-
362
- /**
363
- * The confirm step: the transaction is on its way and Quasar follows it until it is final. It reuses the status and
364
- * progress of Nova Transactions (Sent → Confirming → Paid, in the language of the checkout) and shows the network, the
365
- * amount, the transaction with its explorer link and the sender. The buyer may close the window: the payment keeps
366
- * going.
367
- *
368
- * @returns The confirm step.
369
- */
370
- declare function ConfirmScreen(): react.JSX.Element;
371
-
372
- /**
373
- * 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.
376
- *
377
- * @param props - The answers.
378
- * @param props.onStay - Keeps the checkout open.
379
- * @param props.onLeave - Closes it.
380
- * @returns The question, over the checkout.
381
- */
382
- declare function LeaveDialog({ onStay, onLeave }: {
383
- onStay: () => void;
384
- onLeave: () => void;
385
- }): react.JSX.Element;
386
-
387
- /** Props of {@link LocaleSwitcher}. */
388
- interface LocaleSwitcherProps {
389
- /** The language of the checkout. */
390
- locale: string;
391
- /** The labels of that language. */
392
- labels: NovaPaymentsLabels;
393
- /** Whether the receipt is issued: then the language changes the page only. */
394
- receiptIssued?: boolean;
395
524
  /**
396
- * Called with the language the buyer picks.
525
+ * Classes added to a step (`customization.classNames.step` of `PaymentCheckout`).
397
526
  *
398
- * @param locale - The picked language.
527
+ * @param step - The step.
528
+ * @param index - Its position, from 0.
529
+ * @returns The classes, or nothing.
399
530
  */
400
- onSelect: (locale: CheckoutLocale) => void;
401
- /** Classes added to the wrapper. */
402
- className?: string;
531
+ stepClassName?: (step: CheckoutStep, index: number) => string | undefined;
403
532
  }
404
533
  /**
405
- * The language menu of the checkout: a button with a globe and the language code, always next to the close button,
406
- * that opens the six languages under their own names (each with its `lang`). Arrow keys move, Enter or Space picks,
407
- * Escape closes and gives the focus back to the button; a click outside closes it. Before payment the note says the
408
- * documents follow the language.
409
- *
410
- * Side effect: while open, a `pointerdown` listener on the document closes it on a click outside.
411
- *
412
- * @param props - See {@link LocaleSwitcherProps}.
413
- * @returns The language menu.
414
- */
415
- declare function LocaleSwitcher({ locale, labels, receiptIssued, onSelect, className }: LocaleSwitcherProps): react.JSX.Element;
416
-
417
- /**
418
- * The method step: the token first, then its network (left out when the token has one), then how to pay — from a
419
- * wallet in this browser or with a QR code on a phone. The connected wallet's network comes first and is marked, the
420
- * merchant's Popular methods next; a discount or markup of a method shows on it. Paying from a wallet needs the chain
421
- * adapter of the method's family (`adapters` of `NovaPaymentsProvider`). "Continue" locks the price for the connected
422
- * 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.
534
+ * The steps of the payment, as an ordered list: done steps show a check, the current one is marked
535
+ * `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
536
+ * fit (a phone, a long language), only the current step shows its name; screen readers still read every name.
424
537
  *
425
- * @returns The method step.
538
+ * @param props - See {@link CheckoutStepperProps}.
539
+ * @returns The stepper.
426
540
  */
427
- declare function MethodScreen(): react.JSX.Element | null;
541
+ declare function CheckoutStepper({ steps, labels, className, stepClassName }: CheckoutStepperProps): react.JSX.Element;
428
542
 
429
543
  /** 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.
544
+ type OutcomeKind = Extract<CheckoutScreen, 'unconfirmed' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked'>;
545
+ /** "Contact <seller>": the seller's support email about the invoice, its site, or the app's handler. @internal */
546
+ declare function ContactLink(): react.JSX.Element | null;
547
+ /**
548
+ * An outcome other than paid: a payment Quasar could not confirm (`unconfirmed`: it may still arrive, so the buyer
549
+ * checks the wallet before paying again; only while Quasar still reads it again, `error.rechecked` of the checkout
550
+ * store, the screen says that Quasar checks it for 24 hours and records it for the seller if it arrives; while the
551
+ * store hands a transaction the wallet sent over again, the buyer keeps the page open; otherwise (a reason Quasar never
552
+ * reads again, a hand-over the store gave up) the buyer contacts the seller with the transaction hash, which the screen
553
+ * shows; a transfer that moved money without paying the invoice says so, and one Quasar credited to another invoice
554
+ * says that it pays that one; a transaction the page of another invoice handed over first, which Quasar credits to the
555
+ * invoice whose quoted wallet sent it, and a payment the network confirmed that Quasar has not recorded yet are named
556
+ * with their hash for the seller, and the buyer is asked not to pay again; no payment is offered, only, on a payable
557
+ * invoice and for a payment that may not have left the wallet, "The payment did not leave my wallet", which goes back
558
+ * to it with `payAgain` of the checkout store), an
559
+ * underpaid invoice ("Pay the rest"), a payment the seller reviews (screening,
560
+ * late, overpaid, after the price lock ran out), a refunded invoice, an expired one (with what arrived before the
561
+ * deadline, which the seller can refund; never "nothing was charged" while a payment may still arrive: one this page
562
+ * handed over or saw on its way, or that the wallet sent, also after the checkout stopped following it, which Quasar
563
+ * records and shows to the seller if it arrives, one Quasar could not confirm or reports as unresolved, to check in the
564
+ * wallet, one Quasar does not read again or closed after 24 hours without a result, for the seller with its transaction
565
+ * hash, one that does not pay the invoice and may have moved money, and after a QR code showed, a payment made with it,
566
+ * as this page does not see it; while this page follows a payment on its way, until when it does, `followingUntil` of
567
+ * the checkout store), a cancelled one (the same: never "nothing was charged" while a payment may still
568
+ * arrive, also after a QR code showed, and "recorded if it arrives" only for a payment Quasar records), a corrected one
569
+ * ("Open <new invoice>" opens it here) and a payer the wallet check refused ("Use another wallet"). Each offers to
570
+ * contact the seller.
435
571
  *
436
572
  * @param props - The outcome.
437
573
  * @param props.kind - Which outcome.
@@ -441,38 +577,488 @@ declare function OutcomeScreen({ kind }: {
441
577
  kind: OutcomeKind;
442
578
  }): react.JSX.Element | null;
443
579
 
580
+ /** What every class name function of {@link PaymentCheckoutClassNames} receives. */
581
+ interface CheckoutPartState {
582
+ /** The screen shown. */
583
+ screen: CheckoutScreen;
584
+ /** The state of the checkout store: its phase, the chosen method, the locked price, the last error. */
585
+ checkoutState: CheckoutState;
586
+ /** The checkout, once loaded. */
587
+ checkout: CheckoutView | null;
588
+ }
444
589
  /**
445
- * The paid outcome: the amount, network, time and transaction, the steps done, a refund made later, the receipt to
446
- * 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).
448
- *
449
- * Side effects: navigates to the seller's `successUrl` when the countdown ends.
450
- *
451
- * @returns The paid outcome.
590
+ * Class name functions of the parts of {@link PaymentCheckout}. Each returns classes added after the default ones of
591
+ * its part (or nothing), from the state of the checkout and what the part knows; `className` of a replacement
592
+ * component (`PaymentCheckoutComponents`) gets them too. A color or size a part already sets is changed with the
593
+ * `--tuwa-*` theme variables of `@tuwaio/nova-core`, or by replacing the part: which of two classes for the same
594
+ * property wins depends on the order of the stylesheets.
452
595
  */
453
- declare function PaidScreen(): react.JSX.Element | null;
454
-
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;
596
+ interface PaymentCheckoutClassNames {
461
597
  /**
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.
598
+ * The checkout block with the order panel, the header and the screen (where `className` of `PaymentCheckout` goes:
599
+ * inside the dialog, or the bordered block in the page).
600
+ *
601
+ * @param params - The state of the checkout.
602
+ * @returns Classes to add.
464
603
  */
465
- display?: PaymentCheckoutDisplay;
466
- /** Whether the modal is open (`display="modal"`; default `true`). */
467
- open?: boolean;
604
+ container?: (params: CheckoutPartState) => string | undefined;
468
605
  /**
469
- * Called when the modal opens or closes.
606
+ * The order panel on the left (from 640 px).
470
607
  *
471
- * @param open - The new state.
608
+ * @param params - The state of the checkout.
609
+ * @returns Classes to add.
472
610
  */
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;
611
+ summary?: (params: CheckoutPartState) => string | undefined;
612
+ /**
613
+ * The order above the steps on a phone.
614
+ *
615
+ * @param params - The state of the checkout.
616
+ * @returns Classes to add.
617
+ */
618
+ compactSummary?: (params: CheckoutPartState) => string | undefined;
619
+ /**
620
+ * The header: the steps (or the heading of an outcome), the language menu and the close button.
621
+ *
622
+ * @param params - The state of the checkout.
623
+ * @returns Classes to add.
624
+ */
625
+ header?: (params: CheckoutPartState) => string | undefined;
626
+ /**
627
+ * The list of steps.
628
+ *
629
+ * @param params - The state of the checkout.
630
+ * @returns Classes to add.
631
+ */
632
+ stepper?: (params: CheckoutPartState) => string | undefined;
633
+ /**
634
+ * One step of the list.
635
+ *
636
+ * @param params - The state of the checkout and the step.
637
+ * @param params.step - The step: its key and whether it is done, current or upcoming.
638
+ * @param params.index - Its position, from 0.
639
+ * @returns Classes to add.
640
+ */
641
+ step?: (params: CheckoutPartState & {
642
+ step: CheckoutStep;
643
+ index: number;
644
+ }) => string | undefined;
645
+ /**
646
+ * The area of the screen, under the header. It scrolls in a modal and inline; on a page the window does.
647
+ *
648
+ * @param params - The state of the checkout.
649
+ * @returns Classes to add.
650
+ */
651
+ body?: (params: CheckoutPartState) => string | undefined;
652
+ /**
653
+ * The content of a step screen (buyer details, method, QR code, automatic payments), with its heading.
654
+ *
655
+ * @param params - The state of the checkout.
656
+ * @returns Classes to add.
657
+ */
658
+ screen?: (params: CheckoutPartState) => string | undefined;
659
+ /**
660
+ * The bottom of a screen, with its main button.
661
+ *
662
+ * @param params - The state of the checkout.
663
+ * @returns Classes to add.
664
+ */
665
+ footer?: (params: CheckoutPartState) => string | undefined;
666
+ /**
667
+ * The main button of a screen (Continue, Pay, Sign to pay, Pay the rest…).
668
+ *
669
+ * @param params - The state of the checkout.
670
+ * @returns Classes to add.
671
+ */
672
+ primaryButton?: (params: CheckoutPartState) => string | undefined;
673
+ /**
674
+ * The second action under the main button (back, close, not now, contact).
675
+ *
676
+ * @param params - The state of the checkout.
677
+ * @returns Classes to add.
678
+ */
679
+ secondaryButton?: (params: CheckoutPartState) => string | undefined;
680
+ /**
681
+ * A refusal or error message of a screen.
682
+ *
683
+ * @param params - The state of the checkout.
684
+ * @returns Classes to add.
685
+ */
686
+ error?: (params: CheckoutPartState) => string | undefined;
687
+ /**
688
+ * A token card of the method step.
689
+ *
690
+ * @param params - The state of the checkout and the token.
691
+ * @param params.group - The token and its methods.
692
+ * @param params.selected - Whether it is selected.
693
+ * @returns Classes to add.
694
+ */
695
+ tokenOption?: (params: CheckoutPartState & {
696
+ group: CheckoutTokenGroup;
697
+ selected: boolean;
698
+ }) => string | undefined;
699
+ /**
700
+ * A network option of the method step (when the token is on several networks).
701
+ *
702
+ * @param params - The state of the checkout and the method.
703
+ * @param params.method - The method: the token on this network.
704
+ * @param params.selected - Whether it is selected.
705
+ * @returns Classes to add.
706
+ */
707
+ networkOption?: (params: CheckoutPartState & {
708
+ method: CheckoutMethod;
709
+ selected: boolean;
710
+ }) => string | undefined;
711
+ /**
712
+ * A "Pay with" option of the method step.
713
+ *
714
+ * @param params - The state of the checkout and the option.
715
+ * @param params.payWith - `wallet` (a wallet in this browser) or `qr` (a QR code on a phone).
716
+ * @param params.selected - Whether it is selected.
717
+ * @returns Classes to add.
718
+ */
719
+ payWithOption?: (params: CheckoutPartState & {
720
+ payWith: 'wallet' | 'qr';
721
+ selected: boolean;
722
+ }) => string | undefined;
723
+ /**
724
+ * The card of the seller's consent on the method step (`checkout.consent`): the box the buyer ticks and the seller's
725
+ * words.
726
+ *
727
+ * @param params - The state of the checkout and the consent.
728
+ * @param params.checked - Whether the buyer ticked it.
729
+ * @param params.required - Whether the buyer cannot continue without ticking it.
730
+ * @returns Classes to add.
731
+ */
732
+ consentOption?: (params: CheckoutPartState & {
733
+ checked: boolean;
734
+ required: boolean;
735
+ }) => string | undefined;
736
+ /**
737
+ * A card of grouped facts (the transaction, the rate and fees, the terms of automatic payments).
738
+ *
739
+ * @param params - The state of the checkout.
740
+ * @returns Classes to add.
741
+ */
742
+ detailsCard?: (params: CheckoutPartState) => string | undefined;
743
+ /**
744
+ * A row of a card of facts (rate, network fee, recipient…).
745
+ *
746
+ * @param params - The state of the checkout.
747
+ * @returns Classes to add.
748
+ */
749
+ detailRow?: (params: CheckoutPartState) => string | undefined;
750
+ /**
751
+ * The total of the order panel.
752
+ *
753
+ * @param params - The state of the checkout.
754
+ * @returns Classes to add.
755
+ */
756
+ total?: (params: CheckoutPartState) => string | undefined;
757
+ /**
758
+ * A QR code (Solana Pay, or the payment page for a phone).
759
+ *
760
+ * @param params - The state of the checkout.
761
+ * @returns Classes to add.
762
+ */
763
+ qrCode?: (params: CheckoutPartState) => string | undefined;
764
+ /**
765
+ * The icon of an outcome other than paid.
766
+ *
767
+ * @param params - The state of the checkout and the outcome.
768
+ * @param params.kind - The outcome.
769
+ * @returns Classes to add.
770
+ */
771
+ statusIcon?: (params: CheckoutPartState & {
772
+ kind: OutcomeKind;
773
+ }) => string | undefined;
774
+ /**
775
+ * The chip over the heading of a status screen (Pending, Paid, Failed and the other outcomes).
776
+ *
777
+ * @param params - The state of the checkout, and `tone`, the state the chip shows.
778
+ * @param params.tone - `pending`, `success`, `error` or `neutral`.
779
+ * @returns Classes to add.
780
+ */
781
+ statusChip?: (params: CheckoutPartState & {
782
+ tone: 'pending' | 'success' | 'error' | 'neutral';
783
+ }) => string | undefined;
784
+ /**
785
+ * The strip and the wash of the status color along the top of the checkout, on a payment on its way and its outcome.
786
+ *
787
+ * @param params - The state of the checkout, and `tone`, the state the strip shows.
788
+ * @param params.tone - The state the strip shows.
789
+ * @returns Classes to add.
790
+ */
791
+ statusEdge?: (params: CheckoutPartState & {
792
+ tone: StatusTone;
793
+ }) => string | undefined;
794
+ }
795
+ /** Props of a replacement token card content (`PaymentCheckoutComponents.TokenOption`). */
796
+ interface CheckoutTokenOptionProps {
797
+ /** The token and its methods, one per network. */
798
+ group: CheckoutTokenGroup;
799
+ /** Whether the token is selected. */
800
+ selected: boolean;
801
+ }
802
+ /** Props of a replacement network option content (`PaymentCheckoutComponents.NetworkOption`). */
803
+ interface CheckoutNetworkOptionProps {
804
+ /** The method: the token on this network. */
805
+ method: CheckoutMethod;
806
+ /** Whether it is selected. */
807
+ selected: boolean;
808
+ }
809
+ /** Props of a replacement main button (`PaymentCheckoutComponents.PrimaryButton`): a `<button>`'s props and `busy`. */
810
+ type CheckoutPrimaryButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
811
+ /** The action is running: the default button shows the Quasar loader and is disabled. */
812
+ busy?: boolean;
813
+ };
814
+ /** Props of a replacement QR code (`PaymentCheckoutComponents.QrCode`). */
815
+ interface CheckoutQrCodeProps {
816
+ /** The text the code holds (a Solana Pay URL, or the payment page). */
817
+ value: string;
818
+ /** The text alternative of the code (WCAG 1.1.1). */
819
+ label: string;
820
+ /** The classes of the code: its size, and those of `classNames.qrCode`. */
821
+ className?: string;
822
+ }
823
+ /** Props of a replacement outcome icon (`PaymentCheckoutComponents.StatusIcon`). */
824
+ interface CheckoutStatusIconProps {
825
+ /** The outcome. */
826
+ kind: OutcomeKind;
827
+ /** The classes of `classNames.statusIcon`. */
828
+ className?: string;
829
+ }
830
+ /** Props of a replacement screen (`PaymentCheckoutComponents.screens`). */
831
+ interface CheckoutScreenProps {
832
+ /** The screen it replaces. */
833
+ screen: CheckoutScreen;
834
+ }
835
+ /**
836
+ * Components that replace parts of {@link PaymentCheckout}. A replacement reads the checkout with
837
+ * {@link useCheckoutContext} (the store, its state, the labels of the checkout language, the connected wallet and the
838
+ * actions of the steps).
839
+ */
840
+ interface PaymentCheckoutComponents {
841
+ /** The header: the steps (or the heading of an outcome), the language menu and the close button; on a phone too. */
842
+ Header?: ComponentType<CheckoutHeaderProps>;
843
+ /**
844
+ * The content of the order panel on the left (from 640 px; `classNames.summary` styles the panel around it). On a page
845
+ * the panel is a flex column as tall as the sheet.
846
+ */
847
+ Summary?: ComponentType;
848
+ /** The order above the steps on a phone; `className` holds the classes of `classNames.compactSummary`. */
849
+ CompactSummary?: ComponentType<{
850
+ className?: string;
851
+ }>;
852
+ /** The list of steps, in the header and, on a phone, under the order. */
853
+ Stepper?: ComponentType<CheckoutStepperProps>;
854
+ /** The content of a token card of the method step (the card itself stays a radio button). */
855
+ TokenOption?: ComponentType<CheckoutTokenOptionProps>;
856
+ /** The content of a network option of the method step (the option itself stays a radio button). */
857
+ NetworkOption?: ComponentType<CheckoutNetworkOptionProps>;
858
+ /** The main button of every screen. */
859
+ PrimaryButton?: ComponentType<CheckoutPrimaryButtonProps>;
860
+ /** A QR code. Keep it dark on light: scanners read inverted codes badly. */
861
+ QrCode?: ComponentType<CheckoutQrCodeProps>;
862
+ /** The icon of an outcome other than paid. */
863
+ StatusIcon?: ComponentType<CheckoutStatusIconProps>;
864
+ /** The strip and the wash of the status color along the top of the checkout (`StatusEdge` of `@tuwaio/nova-core`). */
865
+ StatusEdge?: ComponentType<StatusEdgeProps>;
866
+ /** Whole screens, by the screen they replace (for example `paid` or `loading`). */
867
+ screens?: Partial<Record<CheckoutScreen, ComponentType<CheckoutScreenProps>>>;
868
+ }
869
+ /**
870
+ * Handlers of {@link PaymentCheckout}: some wrap an action of the buyer (call `proceed()` or `select()` to run it, or
871
+ * do something else instead), the others tell the app what happened. `onPaid`, `onClose` and `onContact` are props of
872
+ * the checkout.
873
+ */
874
+ interface PaymentCheckoutHandlers {
875
+ /**
876
+ * The buyer picked a token or a network. Without the handler the method is chosen.
877
+ *
878
+ * @param params - The pick.
879
+ * @param params.method - The method picked.
880
+ * @param params.select - Chooses it.
881
+ */
882
+ onMethodSelect?: (params: {
883
+ method: CheckoutMethod;
884
+ select: () => void;
885
+ }) => void;
886
+ /**
887
+ * The buyer pressed "Continue" on the method step. Without the handler the checkout locks the price for the
888
+ * connected wallet (or connects one first), or shows the QR code.
889
+ *
890
+ * @param params - The step.
891
+ * @param params.method - The chosen method.
892
+ * @param params.payWith - `wallet` or `qr`.
893
+ * @param params.proceed - Goes on as the checkout would.
894
+ */
895
+ onQuote?: (params: {
896
+ method: CheckoutMethod;
897
+ payWith: 'wallet' | 'qr';
898
+ proceed: () => Promise<void>;
899
+ }) => void | Promise<void>;
900
+ /**
901
+ * The buyer pressed the pay button ("Pay", "Sign to pay"). Without the handler the wallet prompt opens.
902
+ *
903
+ * @param params - The payment.
904
+ * @param params.quote - The locked price: amount, recipient, network.
905
+ * @param params.method - The method.
906
+ * @param params.proceed - Opens the wallet prompt.
907
+ */
908
+ onSubmit?: (params: {
909
+ quote: CheckoutQuote;
910
+ method: CheckoutMethod;
911
+ proceed: () => Promise<void>;
912
+ }) => void | Promise<void>;
913
+ /**
914
+ * The buyer picked a language. Without the handler the checkout switches to it and saves it on the invoice.
915
+ *
916
+ * @param params - The language.
917
+ * @param params.locale - The language picked.
918
+ * @param params.proceed - Switches and saves it.
919
+ */
920
+ onLocaleChange?: (params: {
921
+ locale: CheckoutLocale;
922
+ proceed: () => Promise<void>;
923
+ }) => void | Promise<void>;
924
+ /**
925
+ * The language the checkout is shown in: called once it is known (the invoice is read, or the app gave the language of
926
+ * its page with `locale`) and on every change, whoever made it: the buyer in the menu, the page with a new `locale`,
927
+ * or the invoice. For a page that keeps `<html lang>`, the labels of Nova or its own texts on the language of the
928
+ * checkout.
929
+ *
930
+ * @param params - The language.
931
+ * @param params.locale - The language shown, a BCP 47 tag: one of the checkout's, or the language of an invoice the
932
+ * checkout has no labels for (it shows English then).
933
+ */
934
+ onLocaleShown?: (params: {
935
+ locale: string;
936
+ }) => void;
937
+ /**
938
+ * The phase of the checkout or the status of the invoice changed; also called once with the first ones.
939
+ *
940
+ * @param params - The state.
941
+ * @param params.phase - The phase of the checkout store.
942
+ * @param params.status - The invoice status, `null` before the invoice loads.
943
+ * @param params.screen - The screen shown.
944
+ */
945
+ onStatusChange?: (params: {
946
+ phase: CheckoutState['phase'];
947
+ status: CheckoutView['invoice']['status'] | null;
948
+ screen: CheckoutScreen;
949
+ }) => void;
950
+ /**
951
+ * The checkout got a new error (Quasar refused an action, or did not answer); the screen shows it.
952
+ *
953
+ * @param params - The error.
954
+ * @param params.error - Its code and message.
955
+ * @param params.screen - The screen shown.
956
+ */
957
+ onError?: (params: {
958
+ error: CheckoutError;
959
+ screen: CheckoutScreen;
960
+ }) => void;
961
+ /**
962
+ * The locked price ran out (`quote`), or the invoice expired (`invoice`). Either can happen while a payment is on its
963
+ * way: the invoice can still close while it confirms (Quasar waits for a payment it learned of
964
+ * before the deadline only for a limited time, and holds a payment that lands later for the seller to accept or
965
+ * return), so do not offer a new invoice at once when `paymentOnTheWay` is `true`; the checkout keeps following the
966
+ * invoice and shows a paid or held outcome if it changes.
967
+ *
968
+ * @param params - What expired.
969
+ * @param params.kind - `quote` or `invoice`.
970
+ * @param params.paymentOnTheWay - A payment is on its way: one this page handed over (`paymentOnTheWay` of the
971
+ * checkout store, or, with an older `@tuwaio/quasar-sdk`, a transaction handed over), one of the invoice Quasar
972
+ * reports (`invoicePaymentOnTheWay`: the page was reopened while it was on its way, another tab paid), or one Quasar
973
+ * could not confirm yet and reads again (`invoicePaymentUnresolved`).
974
+ */
975
+ onExpire?: (params: {
976
+ kind: 'quote' | 'invoice';
977
+ paymentOnTheWay: boolean;
978
+ }) => void;
979
+ }
980
+ /**
981
+ * Options of {@link PaymentCheckout}. Every text and accessible name comes from the labels, and amounts and dates
982
+ * follow the language of the checkout.
983
+ */
984
+ interface PaymentCheckoutConfig {
985
+ /** Animations. They always follow `prefers-reduced-motion`; `disabled: true` turns them off for everyone. */
986
+ animation?: {
987
+ /** Turns the animations off. */
988
+ disabled?: boolean;
989
+ };
990
+ /** Whether the header shows the steps of the payment (default `true`). */
991
+ showSteps?: boolean;
992
+ /**
993
+ * Whether the pay step reads the wallet's balance (through the chain adapter) and, when it is short, offers what the
994
+ * wallet can pay with (default `true`).
995
+ */
996
+ balanceCheck?: boolean;
997
+ /**
998
+ * Minutes before the invoice deadline at which screen readers hear the time left, while the buyer can still pay (not
999
+ * once the payment is on its way) (default `[10, 5, 1]`).
1000
+ */
1001
+ deadlineAnnouncements?: readonly number[];
1002
+ }
1003
+ /** Customization of the Nova Transactions parts the confirm and paid steps show. */
1004
+ interface PaymentCheckoutChildCustomizations {
1005
+ /** The status icon (`TxStatusVisual` of `@tuwaio/nova-transactions`). */
1006
+ statusVisual?: Pick<TxStatusVisualProps, 'className' | 'iconClassNames'>;
1007
+ /** The steps Sent, Confirming, Paid (`TxProgressIndicator` of `@tuwaio/nova-transactions`). */
1008
+ progressIndicator?: Pick<TxProgressIndicatorProps, 'className' | 'stepClassNames' | 'StepComponent'>;
1009
+ /** The transaction with its explorer link (`HashLink` of `@tuwaio/nova-transactions`). */
1010
+ hashLink?: Pick<HashLinkProps, 'className' | 'classNames'>;
1011
+ }
1012
+ /** Customization of {@link PaymentCheckout} (`customization`). */
1013
+ interface PaymentCheckoutCustomization {
1014
+ /** Classes added to the parts, from the state of the checkout. */
1015
+ classNames?: PaymentCheckoutClassNames;
1016
+ /** Components that replace parts. */
1017
+ components?: PaymentCheckoutComponents;
1018
+ /** Handlers that wrap the actions of the buyer or tell what happened. */
1019
+ handlers?: PaymentCheckoutHandlers;
1020
+ /** Options: animations, steps, the balance check, the deadline announcements. */
1021
+ config?: PaymentCheckoutConfig;
1022
+ /** Customization of the Nova Transactions parts of the confirm and paid steps. */
1023
+ childCustomizations?: PaymentCheckoutChildCustomizations;
1024
+ }
1025
+ /** What a part adds to {@link CheckoutPartState} for its class name function. */
1026
+ type PartExtra<K extends keyof PaymentCheckoutClassNames> = Omit<Parameters<NonNullable<PaymentCheckoutClassNames[K]>>[0], keyof CheckoutPartState>;
1027
+ /**
1028
+ * The classes `customization.classNames` adds to a part of the checkout.
1029
+ *
1030
+ * @param context - The checkout context (its customization, screen, store state and checkout).
1031
+ * @param part - The part.
1032
+ * @param extra - What the part adds to the state, such as the method of an option.
1033
+ * @returns The classes, or `undefined`.
1034
+ * @internal
1035
+ */
1036
+ declare function checkoutClassName<K extends keyof PaymentCheckoutClassNames>(context: Pick<CheckoutContextValue, 'customization' | 'screen' | 'state' | 'checkout'>, part: K, extra?: PartExtra<K>): string | undefined;
1037
+
1038
+ /** Where the checkout is shown. */
1039
+ type PaymentCheckoutDisplay = 'modal' | 'inline' | 'page';
1040
+ /** Props of {@link PaymentCheckout}. */
1041
+ interface PaymentCheckoutProps {
1042
+ /** The checkout token of the invoice (its `checkoutToken`, or the end of its `payUrl`). */
1043
+ token: string;
1044
+ /**
1045
+ * `modal` (default): a dialog over the page, 760 px wide (less on a narrower window), a sheet from the bottom under
1046
+ * 640 px; `inline`: a block in the page, as wide as its place up to 760 px; `page`: the whole page, as the Quasar
1047
+ * payment page shows it: a sheet 880 px wide, centered in the window (`min-height: 100svh`; set `--novapay-page-height`
1048
+ * on an ancestor for a page with a header of its own), that grows downward with its step and scrolls nothing inside,
1049
+ * full-bleed under 640 px.
1050
+ */
1051
+ display?: PaymentCheckoutDisplay;
1052
+ /** Whether the modal is open (`display="modal"`; default `true`). */
1053
+ open?: boolean;
1054
+ /**
1055
+ * Called when the modal opens or closes.
1056
+ *
1057
+ * @param open - The new state.
1058
+ */
1059
+ onOpenChange?: (open: boolean) => void;
1060
+ /** Called when the buyer closes the checkout; without it an inline checkout has no close button. */
1061
+ onClose?: () => void;
476
1062
  /** The Quasar API; overrides `baseUrl` of `NovaPaymentsProvider`. */
477
1063
  baseUrl?: string;
478
1064
  /** Calls to make instead of the HTTP ones, for tests and simulations (`CheckoutApi` of `@tuwaio/quasar-sdk/checkout`). */
@@ -482,13 +1068,15 @@ interface PaymentCheckoutProps {
482
1068
  /** How often to read the invoice without an event stream, in milliseconds (default `5000`). */
483
1069
  pollMs?: number;
484
1070
  /**
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.
1071
+ * The payment page of the invoice (its `payUrl` from the Quasar API, passed as it comes): with it, an EVM method can
1072
+ * also be paid by scanning a QR code that opens the page on a phone. `null` (a node without a dashboard URL) or
1073
+ * leaving it out offers the QR code for Solana methods only.
487
1074
  */
488
- payUrl?: string;
1075
+ payUrl?: string | null;
489
1076
  /**
490
- * Connects a wallet of a chain family, for apps without Nova Connect. Inside `NovaConnectProvider` the checkout opens
491
- * its connect modal instead.
1077
+ * Connects a wallet of a chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1078
+ * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection of `NovaPaymentsProvider`)
1079
+ * the checkout opens its connect modal instead.
492
1080
  *
493
1081
  * @param family - The family of the chosen method.
494
1082
  */
@@ -502,14 +1090,47 @@ interface PaymentCheckoutProps {
502
1090
  onPaid?: (invoice: CheckoutView['invoice']) => void;
503
1091
  /**
504
1092
  * 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).
1093
+ * "Stay here" (`0` for no automatic return). Default `5` on a page; `0` in a modal, whose paid outcome offers Close
1094
+ * instead, since the page under it is the seller's (handle the payment there with `onPaid`).
506
1095
  */
507
1096
  autoReturnSeconds?: number;
508
1097
  /** Replaces the link of "Contact <seller>" (the seller's support email, else site) with the app's own handler. */
509
1098
  onContact?: () => void;
1099
+ /**
1100
+ * The language of the page around the checkout, a BCP 47 tag (for example the `lang` of `<html>`). The checkout opens
1101
+ * in it instead of the language of the invoice; a language the checkout does not have is left to the invoice. The
1102
+ * language the buyer picks in the menu wins until this value changes. It changes what the buyer reads, not the
1103
+ * invoice: the documents keep the language of the invoice unless the buyer picks one in the menu.
1104
+ */
1105
+ locale?: string;
510
1106
  /** Classes added to the checkout block. */
511
1107
  className?: string;
1108
+ /**
1109
+ * Class name functions of the parts, from the state of the checkout, and components that replace parts (the
1110
+ * header, the order, the steps, the options of the method step, the main button, the QR code, the outcome icon or
1111
+ * whole screens).
1112
+ */
1113
+ customization?: PaymentCheckoutCustomization;
512
1114
  }
1115
+ /** The screen of the current step or outcome, or its replacement (`customization.components.screens`). @internal */
1116
+ declare function ScreenBody(): react.JSX.Element;
1117
+ /**
1118
+ * The checkout block: the order on the left (from 640 px; on a phone a compact order above the steps), the header
1119
+ * with the steps, language and close, and the current screen. The language follows the invoice, its texts the labels
1120
+ * 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
1121
+ * minutes before the deadline while the buyer can still pay. `customization` adds classes to the order and the screen area, and can replace the
1122
+ * header and the order.
1123
+ *
1124
+ * @internal
1125
+ */
1126
+ declare function CheckoutFrame({ className, withDetails, leave, }: {
1127
+ className?: string;
1128
+ withDetails?: boolean;
1129
+ leave: {
1130
+ onStay: () => void;
1131
+ onLeave: () => void;
1132
+ } | null;
1133
+ }): react.JSX.Element;
513
1134
  /**
514
1135
  * The checkout of a Quasar Payments invoice, opened by its checkout token: the order, the steps of the payment and
515
1136
  * its outcome, in the language of the invoice. It reads the invoice with `createCheckoutStore` of
@@ -526,56 +1147,675 @@ interface PaymentCheckoutProps {
526
1147
  * import { PaymentCheckout } from '@tuwaio/nova-payments';
527
1148
  * import { useState } from 'react';
528
1149
  *
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
- * }
1150
+ * export function PayButton({ token }: { token: string }) {
1151
+ * const [open, setOpen] = useState(false);
1152
+ * return (
1153
+ * <>
1154
+ * <button onClick={() => setOpen(true)}>Pay</button>
1155
+ * <PaymentCheckout token={token} open={open} onOpenChange={setOpen} />
1156
+ * </>
1157
+ * );
1158
+ * }
1159
+ * ```
1160
+ */
1161
+ declare function PaymentCheckout({ token, display, open, onOpenChange, onClose, baseUrl, api, EventSource, pollMs, payUrl, onConnectWallet, onPaid, autoReturnSeconds, onContact, locale: pageLanguage, className, customization, }: PaymentCheckoutProps): react.JSX.Element;
1162
+ /**
1163
+ * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1164
+ * no step can move its top.
1165
+ *
1166
+ * @internal
1167
+ */
1168
+ declare function CheckoutPageRoot({ label, className, children, }: {
1169
+ label: string;
1170
+ className?: string;
1171
+ children: ReactNode;
1172
+ }): react.JSX.Element;
1173
+
1174
+ /** What the parts of a checkout share: its store and state, the screen, the language and its labels. */
1175
+ interface CheckoutContextValue {
1176
+ /** The checkout store of the invoice. */
1177
+ store: CheckoutStore;
1178
+ /** The state of the store. */
1179
+ state: CheckoutState;
1180
+ /** The checkout, once loaded. */
1181
+ checkout: CheckoutView | null;
1182
+ /** The screen shown. */
1183
+ screen: CheckoutScreen;
1184
+ /** The language of the checkout (a BCP 47 tag). */
1185
+ locale: string;
1186
+ /** The labels of that language. */
1187
+ labels: NovaPaymentsLabels;
1188
+ /**
1189
+ * Switches the checkout to the language the buyer picked in the menu and saves it on the invoice, for the documents
1190
+ * still to be issued (`setLocale` of the checkout store). The pick stays the language shown, also over the language of
1191
+ * the page (`locale` of `PaymentCheckout`), until that page changes its language; a pick Quasar did not save is undone.
1192
+ *
1193
+ * @param locale - The language picked.
1194
+ */
1195
+ setLocale: (locale: CheckoutLocale) => Promise<void>;
1196
+ /** `Date.now()` of the latest second tick. */
1197
+ now: number;
1198
+ /**
1199
+ * When this page handed its current payment over (the phase became `confirming`), by the clock of the page; `null`
1200
+ * while no payment of it is confirming, or when it was already confirming as the checkout opened.
1201
+ */
1202
+ handedOverAt: number | null;
1203
+ /** The checkout showed a QR code for the invoice, which the buyer may have paid with from a phone. */
1204
+ qrShown: boolean;
1205
+ /**
1206
+ * This page handed a payment of the invoice over, or saw one on its way, and Quasar did not say that it failed for
1207
+ * good: it may still arrive, also after the store stopped following it.
1208
+ */
1209
+ paymentSent: boolean;
1210
+ /** Closes the checkout; `undefined` when it cannot be closed (inline without `onClose`). */
1211
+ close?: () => void;
1212
+ /** The wallet connected through Satellite Connect, if any. */
1213
+ wallet: CheckoutWallet | null;
1214
+ /** How the buyer pays: from a wallet in this browser, or with a QR code on a phone. */
1215
+ payWith: 'wallet' | 'qr';
1216
+ /**
1217
+ * Sets how the buyer pays.
1218
+ *
1219
+ * @param payWith - `wallet` or `qr`.
1220
+ */
1221
+ setPayWith: (payWith: 'wallet' | 'qr') => void;
1222
+ /** The payment page of the invoice (its `payUrl`), for the QR code of an EVM method; `null` without one. */
1223
+ payUrl?: string | null;
1224
+ /**
1225
+ * Asks the buyer to connect a wallet of the method's chain family; the price is locked for it once connected.
1226
+ *
1227
+ * @param method - The chosen method.
1228
+ * @returns Whether the page can connect a wallet (Nova Connect or the app's handler).
1229
+ */
1230
+ connectWallet: (method: CheckoutMethod) => boolean;
1231
+ /**
1232
+ * Asks the buyer to connect a wallet of a chain family and nothing more: no price is locked for it.
1233
+ *
1234
+ * @param family - The chain family.
1235
+ * @returns Whether the page can connect a wallet.
1236
+ */
1237
+ connectFamily: (family: 'eip155' | 'solana') => boolean;
1238
+ /** Whether the page opened on an invoice already paid: the buyer reads its receipt, nothing was just paid. */
1239
+ openedPaid: boolean;
1240
+ /**
1241
+ * The adapter that pays a chain family from the connected wallet.
1242
+ *
1243
+ * @param family - The family.
1244
+ * @returns The adapter of `NovaPaymentsProvider`, if any.
1245
+ */
1246
+ adapterFor: (family: PaymentFamily) => PaymentsAdapter | undefined;
1247
+ /** The buyer continues on a phone: the QR code of the payment page shows before any price. */
1248
+ handoff: boolean;
1249
+ /**
1250
+ * Shows or hides the QR code of the payment page.
1251
+ *
1252
+ * @param handoff - Whether it shows.
1253
+ */
1254
+ setHandoff: (handoff: boolean) => void;
1255
+ /** Goes back to the method step: forgets the locked price and the phone hand-off. */
1256
+ backToMethods: () => void;
1257
+ /**
1258
+ * Leaves the failed step for the step that pays again (the locked price while it holds, else the methods), and drops
1259
+ * the failure it showed: the buyer has read it.
1260
+ */
1261
+ payAfterFailure: () => void;
1262
+ /**
1263
+ * Whether the buyer continued with a wallet that must confirm the invoice before the price: the step that confirms
1264
+ * it shows while the checkout store waits for the signature (`ConfirmWalletScreen`).
1265
+ */
1266
+ confirmWallet: boolean;
1267
+ /**
1268
+ * Shows or leaves the step that confirms the wallet ("Back to methods").
1269
+ *
1270
+ * @param show - Whether it shows.
1271
+ */
1272
+ setConfirmWallet: (show: boolean) => void;
1273
+ /**
1274
+ * Locks the price for the wallet set on the checkout store, or shows the step that confirms the wallet first while
1275
+ * the store says it must (before the price).
1276
+ *
1277
+ * @returns Resolves when the price is locked, refused, or the step shows.
1278
+ */
1279
+ lockPrice: () => Promise<void>;
1280
+ /**
1281
+ * Takes the payment the wallet sent: the checkout follows it, and hands it over to the app's Pulsar store at once,
1282
+ * where Nova Transactions shows its toast.
1283
+ *
1284
+ * @param payment - The transaction and what it pays.
1285
+ */
1286
+ onPaymentSent: (payment: SentPayment) => void;
1287
+ /** The buyer opened the automatic payments offer after paying a subscription period. */
1288
+ autoPay: boolean;
1289
+ /**
1290
+ * Opens or closes the automatic payments offer.
1291
+ *
1292
+ * @param autoPay - Whether it shows.
1293
+ */
1294
+ setAutoPay: (autoPay: boolean) => void;
1295
+ /** The screen that turns automatic payments off is open (`open`), or they were turned off (`done`). */
1296
+ autoPayOff: 'open' | 'done' | null;
1297
+ /**
1298
+ * Opens or closes the screen that turns automatic payments off, or says they were turned off.
1299
+ *
1300
+ * @param autoPayOff - The new state.
1301
+ */
1302
+ setAutoPayOff: (autoPayOff: 'open' | 'done' | null) => void;
1303
+ /** Whether the wallet has sent the transaction that revokes the permission of this invoice's subscription. */
1304
+ revokeSent: boolean;
1305
+ /**
1306
+ * Keeps that for as long as the page shows the invoice, so the buyer leaving the screen does not send it twice.
1307
+ *
1308
+ * @param sent - Whether it was sent.
1309
+ */
1310
+ setRevokeSent: (sent: boolean) => void;
1311
+ /**
1312
+ * Opens another invoice in this checkout: the one that replaced a corrected invoice.
1313
+ *
1314
+ * @param token - Its checkout token.
1315
+ */
1316
+ openInvoice: (token: string) => void;
1317
+ /** Replaces the link of "Contact <seller>", when the app handles it. */
1318
+ onContact?: () => void;
1319
+ /** Seconds before the paid outcome sends the buyer back to the seller; `0` for no automatic return. */
1320
+ autoReturnSeconds: number;
1321
+ /**
1322
+ * How the checkout shows (`display` of `PaymentCheckout`): a modal belongs to the page under it, so its paid outcome
1323
+ * closes it instead of sending the buyer back to the seller's page.
1324
+ */
1325
+ display: PaymentCheckoutDisplay;
1326
+ /** Class name functions and replacement components of the parts (`customization` of `PaymentCheckout`). */
1327
+ customization: PaymentCheckoutCustomization;
1328
+ }
1329
+ declare const CheckoutContext: react.Context<CheckoutContextValue | null>;
1330
+ /** Gives the parts of a checkout what they share. @internal */
1331
+ declare const CheckoutContextProvider: react.Provider<CheckoutContextValue | null>;
1332
+
1333
+ /** The merchant's logo (or the first letter of its name), name and website, and the test badge. @internal */
1334
+ declare function MerchantBadge({ compact }: {
1335
+ compact?: boolean;
1336
+ }): react.JSX.Element | null;
1337
+ /** The seller as the invoice document names them, the merchant's policies and what Quasar is. @internal */
1338
+ declare function SellerDetailsContent({ checkout, labels }: {
1339
+ checkout: CheckoutView;
1340
+ labels: NovaPaymentsLabels;
1341
+ }): react.JSX.Element;
1342
+ /**
1343
+ * The countdown to the invoice deadline, through every step of the payment until it succeeded (`deadlineState`); it
1344
+ * stays at 00:00 when the deadline passes while the payment confirms. @internal
1345
+ */
1346
+ declare function DeadlineTimer(): react.JSX.Element | null;
1347
+ /** The lines, subtotal and tax of the invoice. @internal */
1348
+ declare function OrderLines(): react.JSX.Element | null;
1349
+ /** The total of the invoice, which stays in place while the lines scroll. @internal */
1350
+ declare function OrderTotal(): react.JSX.Element | null;
1351
+ /** "Secured by Quasar" and the seller's support email, at the same place on every step (WCAG 3.2.6). @internal */
1352
+ declare function SummaryFooter(): react.JSX.Element;
1353
+ /** A button that shows or hides a part, with `aria-expanded` and `aria-controls`. @internal */
1354
+ declare function Disclosure({ label, children, className, buttonClassName, growsUp, }: {
1355
+ label: string;
1356
+ children: ReactNode;
1357
+ className?: string;
1358
+ buttonClassName?: string;
1359
+ /** The part stands at the bottom of its panel, so its content pushes the button upwards: the arrow says so. */
1360
+ growsUp?: boolean;
1361
+ }): react.JSX.Element;
1362
+ /**
1363
+ * The order panel on the left of the checkout (from 640 px): the merchant, the seller details (unfolded in place, the
1364
+ * lines scroll while the deadline and the total stay), the countdown to the deadline (through every step of the
1365
+ * payment, also while it confirms, until it succeeded), the lines and the total, and the help.
1366
+ *
1367
+ * @returns The order panel.
1368
+ */
1369
+ declare function CheckoutSummary(): react.JSX.Element | null;
1370
+ /**
1371
+ * The order on a phone, above the steps: the total and the countdown to the deadline (until the payment succeeded), with
1372
+ * the lines and the seller details behind a "Details" button.
1373
+ *
1374
+ * @param props - The classes.
1375
+ * @param props.className - Classes added to the order (`customization.classNames.compactSummary`).
1376
+ * @returns The compact order.
1377
+ */
1378
+ declare function CompactSummary({ className }?: {
1379
+ className?: string;
1380
+ }): react.JSX.Element | null;
1381
+
1382
+ /**
1383
+ * The confirm step: the transaction is on its way and Quasar follows it until it is final. Its head is the one of every
1384
+ * status screen (the Quasar loader, the chip "Pending", the heading and the amount, which the paid and the failed step
1385
+ * go on from), with the progress of Nova Transactions (Sent → Confirming → Paid, in the language of the checkout), the
1386
+ * network, the transaction with its explorer link and the sender. The buyer may close the window: the payment keeps
1387
+ * going. It also shows a payment of the invoice that this page did not hand over while Quasar reports it on its way
1388
+ * (the page was reopened or reloaded, another tab paid, Quasar found a Solana Pay transfer), instead of offering to pay
1389
+ * again: its note asks the buyer to wait for it. When the invoice deadline passes while a payment is on its way (the
1390
+ * countdown of the order stays at 00:00), and the invoice is still `open` or `underpaid`, the note follows the payment:
1391
+ * sent before the deadline, it says that the payment was sent in time and is being confirmed (Quasar keeps the invoice
1392
+ * open for a payment it learned of before the deadline while it confirms: for this page's payment Quasar's word on it
1393
+ * decides, `paymentSentInTime` of the checkout store, whatever the clock of the page says; else `paymentCountsUntil`;
1394
+ * with a Quasar that reports neither, a payment this page handed over before the deadline by its clock); otherwise it
1395
+ * says that the seller accepts or returns a payment that arrives after the invoice closes. A payment that failed or settled is no
1396
+ * longer on its way, and the usual note comes back. While the store hands the transaction over again, as Quasar is out of
1397
+ * reach for a moment, the note asks to keep the page open: closing it is what could lose the hand-over.
1398
+ *
1399
+ * @returns The confirm step.
1400
+ */
1401
+ declare function ConfirmScreen(): react.JSX.Element;
1402
+
1403
+ /**
1404
+ * The step that confirms the paying wallet, right after the wallet and the method and before
1405
+ * the price, for an EVM payment the buyer's wallet sends itself (`payerProof` of the checkout store is `required`): one
1406
+ * sentence that it is free and moves no money, the summary of what the wallet signs (the invoice, the seller, the
1407
+ * amount and the wallet), and the main button that opens the wallet's signature request. Meanwhile the window of the
1408
+ * wallet covers the step, with the site the message names to check, a line that the wallet may show it as a sign-in
1409
+ * request for that site, and "Try again" (signing again moves no money); a smart wallet is said to ask for its passkey.
1410
+ * Once the window is closed the button works again, also while the wallet never answered. A refusal keeps the buyer
1411
+ * on the step, with its reason and the same button to try again; "Back to methods" returns to the methods (or to the
1412
+ * underpaid invoice whose rest another wallet pays). Once the wallet signed, the price is locked on this step and the
1413
+ * pay step follows. One signature per invoice and wallet: a new price or token needs no new one, nor a new network for
1414
+ * an ordinary wallet (a smart wallet's signature counts on its network only).
1415
+ *
1416
+ * Side effects: wallet prompts (a network switch, the signature); `POST payer-proof/message`, `POST payer-proof` and
1417
+ * `POST quote` through the checkout store.
1418
+ *
1419
+ * @returns The step.
1420
+ */
1421
+ declare function ConfirmWalletScreen(): react.JSX.Element | null;
1422
+
1423
+ /**
1424
+ * The failed step: a payment this page showed on its way failed for good (the network reverted it, the wallet
1425
+ * cancelled it, a Solana transaction expired), and the invoice still takes a payment. It stays where the confirm step
1426
+ * was, with the same head, so the buyer sees what became of the payment they were watching: the mark and the chip turn
1427
+ * to a failure, the last step says "Failed", and under the network, the transaction with its explorer link and the
1428
+ * sender stands why, in the words of the reason. "Pay again" goes on to the step the checkout store went back to (the
1429
+ * locked price while it holds, else the methods); "Contact" reaches the seller.
1430
+ *
1431
+ * @returns The failed step, or nothing without the failure of a payment.
1432
+ */
1433
+ declare function FailedScreen(): react.JSX.Element | null;
1434
+
1435
+ /**
1436
+ * The question when the buyer closes the checkout before anything is sent: the invoice stays open until its deadline,
1437
+ * reopened from the email or the seller's site, and the locked price is released. It is a Nova dialog of its own, over
1438
+ * the checkout: one backdrop dims the whole screen, the checkout and its frame included (a layer inside the checkout
1439
+ * left its frame sharp around the dimmed content); on a phone it slides up from the bottom like the other Nova dialogs.
1440
+ * "Stay and pay", Escape or a click outside keep the checkout and give the focus back where it was, "Leave" closes it.
1441
+ * The heading takes the focus.
1442
+ *
1443
+ * @param props - The answers.
1444
+ * @param props.onStay - Keeps the checkout open.
1445
+ * @param props.onLeave - Closes it.
1446
+ * @returns The question, over the checkout.
1447
+ */
1448
+ declare function LeaveDialog({ onStay, onLeave }: {
1449
+ onStay: () => void;
1450
+ onLeave: () => void;
1451
+ }): react.JSX.Element;
1452
+
1453
+ /** Props of {@link LocaleSwitcher}. */
1454
+ interface LocaleSwitcherProps {
1455
+ /** The language of the checkout. */
1456
+ locale: string;
1457
+ /** The labels of that language. */
1458
+ labels: NovaPaymentsLabels;
1459
+ /** Whether the receipt is issued: then the language changes the page only. */
1460
+ receiptIssued?: boolean;
1461
+ /**
1462
+ * Called with the language the buyer picks.
1463
+ *
1464
+ * @param locale - The picked language.
1465
+ */
1466
+ onSelect: (locale: CheckoutLocale) => void;
1467
+ /** Classes added to the wrapper. */
1468
+ className?: string;
1469
+ }
1470
+ /**
1471
+ * The language menu of the checkout: a button with a globe and the language code, always next to the close button,
1472
+ * that opens the six languages under their own names (each with its `lang`). Arrow keys move, Enter or Space picks,
1473
+ * Escape closes and gives the focus back to the button; a click outside closes it. Before payment the note says the
1474
+ * documents follow the language.
1475
+ *
1476
+ * Side effect: while open, a `pointerdown` listener on the document closes it on a click outside.
1477
+ *
1478
+ * @param props - See {@link LocaleSwitcherProps}.
1479
+ * @returns The language menu.
1480
+ */
1481
+ declare function LocaleSwitcher({ locale, labels, receiptIssued, onSelect, className }: LocaleSwitcherProps): react.JSX.Element;
1482
+
1483
+ /**
1484
+ * The method step: the token first, then its network (left out when the token has one), then how to pay — from a
1485
+ * wallet in this browser or with a QR code on a phone. The connected wallet's network comes first and is marked, the
1486
+ * merchant's Popular methods next; a discount or markup of a method shows on it. Paying from a wallet needs the chain
1487
+ * adapter of the method's family (`adapters` of `NovaPaymentsProvider`). "Continue" locks the price for the connected
1488
+ * wallet (or connects one first), locks it without a payer for a Solana Pay QR code, or shows the QR code of the
1489
+ * payment page for an EVM method paid on a phone; a wallet that must confirm the invoice first (an EVM payment it sends
1490
+ * itself) goes to the step that confirms it before the price. A consent the seller asks (`checkout.consent`) is a box the buyer
1491
+ * ticks under the ways to pay; a required one keeps "Continue" off until it is ticked, and the quote carries it.
1492
+ *
1493
+ * @returns The method step.
1494
+ */
1495
+ declare function MethodScreen(): react.JSX.Element | null;
1496
+
1497
+ /**
1498
+ * The paid outcome: the amount, network, time and transaction (every transfer of an invoice paid in parts, each with
1499
+ * its time, amount and explorer link), the steps done, a refund made later, the receipt to
1500
+ * download, the automatic payments offer of a subscription, and the way back to the seller (`successUrl`) with a
1501
+ * visible countdown and "Stay here" (WCAG 2.2.1). In a modal it offers Close instead: the page under it is the
1502
+ * seller's, and loading it again would close everything at once.
1503
+ *
1504
+ * Side effects: navigates to the seller's `successUrl` when the countdown ends.
1505
+ *
1506
+ * @returns The paid outcome.
1507
+ */
1508
+ declare function PaidScreen(): react.JSX.Element | null;
1509
+
1510
+ /**
1511
+ * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
1512
+ * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
1513
+ * the recipient, and the main action — "Sign to pay" when the merchant pays the gas, "Pay" otherwise, "Switch to …"
1514
+ * on the wrong network, "Confirm this wallet to pay" before a transfer or a paymaster payment of a method the gasless
1515
+ * relay could pay (the wallet signs Quasar's free confirmation of the invoice first; the relay's authorization needs
1516
+ * none). Before the prompt it reads the wallet's balance (unless `config.balanceCheck` is `false`)
1517
+ * and, when it is short, offers the methods the wallet can pay and the seller's top-up link. `handlers.onSubmit` wraps
1518
+ * the pay button. A Solana payment off mainnet reminds the buyer to switch the wallet to its cluster (Solana wallets
1519
+ * choose their network themselves), with the steps of Phantom and Solflare. The note under the buttons says that the
1520
+ * payment goes straight to the merchant and, when the merchant checks paying wallets (`amlScreening` of the
1521
+ * checkout), that it does.
1522
+ *
1523
+ * Side effects: balance, fee and wallet capability reads from the network through the chain adapter (no request to
1524
+ * Quasar); wallet prompts; checkout requests to Quasar; on a Solana payment, `switchNetwork` of the Satellite store
1525
+ * moves the app's Solana connection to the payment's cluster (no wallet request).
1526
+ *
1527
+ * @returns The pay step.
1528
+ */
1529
+ declare function PayScreen(): react.JSX.Element | null;
1530
+
1531
+ /**
1532
+ * The QR code step. For Solana, a Solana Pay transfer request a phone wallet scans (or opens with "Open in wallet
1533
+ * app"), with the exact amount, the recipient, the price lock and a warning against paying from an exchange; the page
1534
+ * waits for the payment, which Quasar finds by the reference key. For an EVM method, the QR code of the payment page
1535
+ * opens this checkout on the phone, before any price.
1536
+ *
1537
+ * @returns The QR code step.
1538
+ */
1539
+ declare function QrScreen(): react.JSX.Element | null;
1540
+
1541
+ /** What a refund asks for: the amount and mode `start` takes (`RefundParams` of `@tuwaio/quasar-sdk`). */
1542
+ type RefundRequest = Parameters<RefundState['start']>[1];
1543
+ /**
1544
+ * Where a refund stands for the merchant: `amount` (what to refund), `requesting`, `connect` (a wallet of the
1545
+ * payment's network), `confirm`, `switching` and `wallet` (the wallet asks), `submitting`, `confirming` (the network
1546
+ * confirms it), `confirmed` or `failed`.
1547
+ */
1548
+ type RefundStep = 'amount' | 'requesting' | 'connect' | 'confirm' | 'switching' | 'wallet' | 'submitting' | 'confirming' | 'confirmed' | 'failed';
1549
+ /**
1550
+ * Why a refund was not sent: the wallet holds too little (`notEnough`), the merchant declined, the wallet cannot send
1551
+ * it or sent it on another network, it failed, Quasar does not know the payer (`noRecipient`), or Quasar did not answer when
1552
+ * the window looked again before asking the wallet (`unreachable`), the wallet is the one that paid and would only pay the
1553
+ * fee (`fromBuyer`), or the merchant closed the wait while the request stays open in the wallet (`stillInWallet`).
1554
+ */
1555
+ type RefundProblem = 'notEnough' | 'declined' | 'unsupported' | 'wrongNetwork' | 'failed' | 'noRecipient' | 'unreachable' | 'fromBuyer' | 'stillInWallet';
1556
+ /** What {@link useRefund} needs. */
1557
+ interface UseRefundParams {
1558
+ /** The refund store (`createRefundStore` of `@tuwaio/quasar-sdk/checkout`). */
1559
+ store: RefundStore;
1560
+ /** The paid invoice to refund. */
1561
+ invoiceId: string;
1562
+ /** Its number, for the transaction in Pulsar (the ID without one). */
1563
+ invoice?: string;
1564
+ /** The refund the app worked out: asked for at once, without the amount step. */
1565
+ params?: RefundRequest;
1566
+ /** Whether the window is open: when it opens again after a confirmed refund, it starts over for another one. */
1567
+ open?: boolean;
1568
+ /** The labels of the language. */
1569
+ labels: NovaPaymentsLabels;
1570
+ /** The language, for amounts. */
1571
+ locale: string;
1572
+ /**
1573
+ * Connects a wallet of the payment's chain family, for apps without Nova Connect (the `onConnectWallet` of
1574
+ * `NovaPaymentsProvider` otherwise). Inside `NovaConnectProvider` the refund opens its connect modal instead.
1575
+ *
1576
+ * @param family - The chain family of the payment.
1577
+ */
1578
+ onConnectWallet?: (family: PaymentFamily) => void;
1579
+ }
1580
+ /** What {@link useRefund} returns. */
1581
+ interface RefundFlow {
1582
+ /** Where the refund stands. */
1583
+ step: RefundStep;
1584
+ /** The refund store's phase. */
1585
+ phase: RefundPhase;
1586
+ /**
1587
+ * What a refund would send, before it is asked for: a requested refund holds its amount until it is sent.
1588
+ *
1589
+ * @param request - What to refund.
1590
+ * @returns The preview; `null` when the store cannot show one; `refused` when Quasar would refuse it (`error` says why).
1591
+ */
1592
+ preview: (request: RefundRequest) => Promise<RefundPreview | 'refused' | null>;
1593
+ /** The refund, once asked for. */
1594
+ refund: RefundState['refund'];
1595
+ /** Why the last request to Quasar failed. */
1596
+ error: CheckoutError | null;
1597
+ /** What the wallet sends, or `null` before the refund is asked for or without a payer. */
1598
+ transfer: PaymentInstructions | null;
1599
+ /** The CAIP-2 chain of the payment. */
1600
+ chainId: string | null;
1601
+ /** The name of its network. */
1602
+ network: string;
1603
+ /** The amount to send with its symbol. */
1604
+ amount: string;
1605
+ /** The connected wallet, when it is of the payment's chain family. */
1606
+ wallet: CheckoutWallet | null;
1607
+ /** Whether the EVM wallet is on another network than the payment's: {@link RefundFlow.switchNetwork} first. */
1608
+ wrongNetwork: boolean;
1609
+ /** What the wallet holds of the asset: `undefined` while read, `null` when unknown. */
1610
+ balance: bigint | null | undefined;
1611
+ /** The estimated network fee. */
1612
+ fee: NativeFee | null | undefined;
1613
+ /** Why the refund was not sent, until the next try. */
1614
+ problem: RefundProblem | null;
1615
+ /** The transaction the wallet sent; while Quasar has not taken it, {@link RefundFlow.send} hands it over again. */
1616
+ txKey: string | null;
1617
+ /** The explorer link of a transaction of the refund, when the chain has one. */
1618
+ transactionUrl: (hash: string) => string | undefined;
1619
+ /** The explorer link of an address on the chain of the refund, when the chain has one. */
1620
+ addressUrl: (address: string) => string | undefined;
1621
+ /** Whether the page can connect a wallet. */
1622
+ canConnect: boolean;
1623
+ /** Whether the connect modal is open. */
1624
+ connecting: boolean;
1625
+ /**
1626
+ * Asks Quasar for the refund.
1627
+ *
1628
+ * @param params - Amount, mode and reason.
1629
+ */
1630
+ start: (params: RefundRequest) => Promise<void>;
1631
+ /** Asks the merchant to connect a wallet of the payment's chain family. */
1632
+ connect: () => void;
1633
+ /** Asks the EVM wallet to switch to the payment's network; sends nothing. */
1634
+ switchNetwork: () => Promise<void>;
1635
+ /** Sends the refund from the wallet (switching its network first) and hands its transaction to Quasar. */
1636
+ send: () => Promise<void>;
1637
+ /**
1638
+ * Closes the wait for the wallet. Its request stays open there: a transaction it sends later is still handed to Quasar, a
1639
+ * refusal is not shown, and {@link RefundFlow.send} asks it nothing more meanwhile.
1640
+ */
1641
+ dismiss: () => void;
1642
+ /** Whether a send is under way, from the press on: the button shows it, and another press sends nothing. */
1643
+ sending: boolean;
1644
+ }
1645
+ /**
1646
+ * Refunds a payment from the merchant's connected wallet: asks Quasar for the refund through the store,
1647
+ * sends its transfer to the payer with the payments adapter of the chain family (switching the wallet to the payment's
1648
+ * network first, and never prompting a wallet that holds too little), hands the transaction to Quasar and lets the
1649
+ * store follow it until Quasar confirms it and issues the credit note. A transaction the wallet sent is handed over
1650
+ * again on the next {@link RefundFlow.send}, never sent twice. Before the wallet is asked the refund is read again, and nothing
1651
+ * goes out when it no longer waits or Quasar does not answer. With the app's Pulsar store (`pulsar` of
1652
+ * `NovaPaymentsProvider`) and an adapter that describes its transactions, the refund is also tracked by Pulsar, and
1653
+ * Nova Transactions shows its toast.
1654
+ *
1655
+ * Side effects: the store's calls; wallet prompts; balance and fee reads from the network; the Pulsar store.
1656
+ *
1657
+ * @param params - See {@link UseRefundParams}.
1658
+ * @returns See {@link RefundFlow}.
1659
+ */
1660
+ declare function useRefund({ store, invoiceId, invoice, params, open, labels, locale, onConnectWallet, }: UseRefundParams): RefundFlow;
1661
+
1662
+ /** A refund of the store (`Refund` of `@tuwaio/quasar-sdk`). */
1663
+ type Refund = NonNullable<RefundState['refund']>;
1664
+ /** Props of {@link RefundDialog}. */
1665
+ interface RefundDialogProps {
1666
+ /** Whether the window is open. */
1667
+ open: boolean;
1668
+ /**
1669
+ * Opens or closes the window.
1670
+ *
1671
+ * @param open - Whether it is open.
1672
+ */
1673
+ onOpenChange: (open: boolean) => void;
1674
+ /**
1675
+ * The refund store (`createRefundStore` of `@tuwaio/quasar-sdk/checkout`), whose calls the app runs on its server
1676
+ * with the secret key. One store per invoice: it keeps the refund while the window is closed.
1677
+ */
1678
+ store: RefundStore;
1679
+ /** The paid invoice to refund. */
1680
+ invoiceId: string;
1681
+ /** Its number, shown in the title and in the transaction of Pulsar. */
1682
+ invoice?: string;
1683
+ /** The refund the app worked out (amount, mode, reason): asked for at once, without the amount step. */
1684
+ params?: RefundRequest;
1685
+ /** The invoice currency, for the amount step. Defaults to `USD`. */
1686
+ currency?: string;
1687
+ /** What is left to refund, with its currency, shown under the amount (`20.00 USD`). */
1688
+ refundable?: string;
1689
+ /** The language (a BCP 47 tag). Defaults to `en`. */
1690
+ locale?: string;
1691
+ /** Rows the app adds: to the confirm step (what the refund takes back) and to the refunded step. */
1692
+ details?: {
1693
+ confirm?: ReactNode;
1694
+ done?: ReactNode;
1695
+ };
1696
+ /** "Record refund": the app's form for a refund sent another way; offered when the wallet does not send it. */
1697
+ onRecord?: () => void;
1698
+ /**
1699
+ * Connects a wallet of the payment's chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1700
+ * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection) the window opens its
1701
+ * connect modal instead.
1702
+ *
1703
+ * @param family - The chain family of the payment.
1704
+ */
1705
+ onConnectWallet?: (family: PaymentFamily) => void;
1706
+ /**
1707
+ * Called once Quasar confirmed the refund and issued its credit note.
1708
+ *
1709
+ * @param refund - The confirmed refund (`Refund` of `@tuwaio/quasar-sdk`).
1710
+ */
1711
+ onRefunded?: (refund: NonNullable<RefundState['refund']>) => void;
1712
+ }
1713
+ /** Props of {@link RefundButton}. */
1714
+ interface RefundButtonProps extends Omit<RefundDialogProps, 'open' | 'onOpenChange'> {
1715
+ /** The button's text. Defaults to the `refund.button` label. */
1716
+ label?: ReactNode;
1717
+ /** Classes of the button. */
1718
+ className?: string;
1719
+ /** Whether the button is disabled. */
1720
+ disabled?: boolean;
1721
+ }
1722
+ /**
1723
+ * A button that refunds a paid invoice from the merchant's connected wallet: it opens {@link RefundDialog}. Put it
1724
+ * inside {@link NovaPaymentsProvider}: it uses the provider's wallet connection (the app's Satellite store and Nova
1725
+ * Connect when the app has them, else Nova's own `ownConnection`) and its adapters. In an app whose wallets connect
1726
+ * without Nova Connect, pass `onConnectWallet` here or to the provider.
1727
+ *
1728
+ * @param props - See {@link RefundButtonProps}.
1729
+ * @returns The button and its window.
1730
+ *
1731
+ * @example
1732
+ * ```tsx
1733
+ * import { createRefundStore } from '@tuwaio/quasar-sdk/checkout';
1734
+ * import { RefundButton } from '@tuwaio/nova-payments';
1735
+ *
1736
+ * // refundInvoice, submitRefund and getRefund are Server Actions calling quasar.payments
1737
+ * const refunds = createRefundStore({ request: refundInvoice, submit: submitRefund, get: getRefund });
1738
+ *
1739
+ * <RefundButton store={refunds} invoiceId={invoice.id} invoice={invoice.number} currency="USD" />;
538
1740
  * ```
539
1741
  */
540
- declare function PaymentCheckout({ token, display, open, onOpenChange, onClose, baseUrl, api, EventSource, pollMs, payUrl, onConnectWallet, onPaid, autoReturnSeconds, onContact, className, }: PaymentCheckoutProps): react.JSX.Element;
541
-
1742
+ declare function RefundButton({ label, className, disabled, ...props }: RefundButtonProps): react.JSX.Element;
542
1743
  /**
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.
1744
+ * The window of a refund from the merchant's wallet: what to refund (skipped
1745
+ * with `params`), a wallet of the payment's network, the confirmation (what goes where, from which wallet with its
1746
+ * balance, the network fee, and the app's rows), the wallet's prompt, the transaction on its way, and the credit note.
1747
+ * A refund the wallet did not send says why, offers to send it again and the app's "Record refund". The refund
1748
+ * goes on while the window is closed: the store follows it.
548
1749
  *
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.
1750
+ * Side effects: those of `useRefund` (the store's calls, wallet prompts, balance and fee reads, the Pulsar store).
551
1751
  *
552
- * @returns The pay step.
1752
+ * @param props - See {@link RefundDialogProps}.
1753
+ * @returns The window.
553
1754
  */
554
- declare function PayScreen(): react.JSX.Element | null;
555
-
1755
+ declare function RefundDialog({ open, onOpenChange, locale, onRefunded, ...props }: RefundDialogProps): react.JSX.Element;
1756
+ /** The step of a refund the window shows. @internal */
1757
+ declare function RefundSteps({ flow, labels, locale, close, currency, refundable, details, onRecord, }: Pick<RefundDialogProps, 'currency' | 'refundable' | 'details' | 'onRecord'> & {
1758
+ flow: RefundFlow;
1759
+ labels: NovaPaymentsLabels;
1760
+ locale: string;
1761
+ close: () => void;
1762
+ }): react.JSX.Element;
1763
+ /** Whether a refund has been on its way for long, from when it last changed. @internal */
1764
+ declare const isSlow: (refund: Pick<Refund, "createdAt" | "updatedAt"> | null | undefined) => boolean;
1765
+ /** A refusal of Quasar in the words of the window, or of the app when it said it in the reader's language. @internal */
1766
+ declare const refusalText: (error: {
1767
+ code: string;
1768
+ text?: string;
1769
+ }, text: NovaPaymentsLabels["refund"]) => string;
556
1770
  /**
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.
1771
+ * A refund whose transaction failed on-chain: why, then the same refund asked for again, priced now, or recorded.
561
1772
  *
562
- * @returns The QR code step.
1773
+ * @internal
563
1774
  */
564
- declare function QrScreen(): react.JSX.Element | null;
1775
+ declare function FailedStep({ flow, labels, locale, values, recordAction, close, }: {
1776
+ flow: RefundFlow;
1777
+ labels: NovaPaymentsLabels;
1778
+ locale: string;
1779
+ values: Record<string, string>;
1780
+ recordAction: ReactNode;
1781
+ close: () => void;
1782
+ }): react.JSX.Element;
1783
+ /**
1784
+ * What to refund: an amount of the invoice currency (everything left when empty) or everything received.
1785
+ *
1786
+ * @internal
1787
+ */
1788
+ declare function AmountStep({ flow, labels, locale, currency, refundable, }: {
1789
+ flow: RefundFlow;
1790
+ labels: NovaPaymentsLabels;
1791
+ locale: string;
1792
+ currency: string;
1793
+ refundable?: string;
1794
+ }): react.JSX.Element;
1795
+ declare function ConfirmStep({ flow, labels, locale, values, details, recordAction, }: {
1796
+ flow: RefundFlow;
1797
+ labels: NovaPaymentsLabels;
1798
+ locale: string;
1799
+ values: Record<string, string>;
1800
+ details?: ReactNode;
1801
+ recordAction: ReactNode;
1802
+ }): react.JSX.Element;
565
1803
 
566
1804
  /**
567
1805
  * What the wallet asks for: a gasless signature, a transaction, a network switch, the permission of automatic
568
- * payments, or Quasar takes the payment.
1806
+ * payments, the signature that confirms the paying wallet (`proof`), or Quasar takes the payment.
569
1807
  */
570
- type WalletPromptKind = 'sign' | 'confirm' | 'switch' | 'permission' | 'submitting';
1808
+ type WalletPromptKind = 'sign' | 'confirm' | 'switch' | 'permission' | 'proof' | 'submitting';
571
1809
  /** Props of {@link WalletPrompt}. */
572
1810
  interface WalletPromptProps {
573
1811
  /** What the wallet asks for. */
574
1812
  kind: WalletPromptKind;
575
- /** The wallet's name. */
1813
+ /** The wallet's name, as it calls itself (`name` of the connected wallet). */
576
1814
  walletName: string;
577
- /** The wallet's id, for its icon. */
1815
+ /** The wallet's id, for the icon Nova has of it when the wallet gives none. */
578
1816
  walletId: string;
1817
+ /** The icon the wallet gives itself (`icon` of the connected wallet), usually a `data:` URI. */
1818
+ walletIcon?: string;
579
1819
  /** The amount with its symbol. */
580
1820
  amount: string;
581
1821
  /** The seller. */
@@ -588,19 +1828,42 @@ interface WalletPromptProps {
588
1828
  priceTime: string | null;
589
1829
  /** Asks the wallet again; only where a second request cannot pay twice (a signature). */
590
1830
  onRetry?: () => void;
1831
+ /** What the window says instead of the text of its kind (the signature that confirms the wallet). */
1832
+ text?: string;
1833
+ /** The rows to check in the wallet instead of the payment's (the signature that confirms the wallet). */
1834
+ details?: {
1835
+ name: string;
1836
+ value: string;
1837
+ }[];
1838
+ /** A line under the text: how the wallet may present the request (the signature that confirms the wallet). */
1839
+ hint?: string;
591
1840
  /** Closes the window. */
592
1841
  onCancel: () => void;
1842
+ /**
1843
+ * The height in px of the step the window stands for, measured while the step showed and capped at the room of the
1844
+ * checkout pane. Below 640 px, where the checkout has no fixed height, the window keeps it as its minimum height, so
1845
+ * the sheet does not shrink while the wallet asks and grow back after. Wider screens have the fixed height of the
1846
+ * checkout and ignore it.
1847
+ */
1848
+ stepHeight?: number | null;
593
1849
  }
594
1850
  /**
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.
1851
+ * The window that stands for the pay step while the wallet asks the buyer: what to sign or confirm, and what to check
1852
+ * in the wallet before — the amount, the recipient, the network and the time left of the price (WCAG 3.3.4); for the
1853
+ * signature that confirms the paying wallet, the invoice, the seller and the site the message names. It sits in the
1854
+ * flow of the screen, in place of the step: a screen that shows it (a custom screen of
1855
+ * `customization.components.screens` too) hides its step while it shows, with `display: none` and `inert` (the step
1856
+ * keeps its state), so the window fills the checkout pane, centered, without the scrollbar of a taller step, and
1857
+ * passes the step's height as `stepHeight`, so a phone keeps the height of the sheet. The heading takes the focus, so
1858
+ * screen readers say what happens; when the window closes and the step comes back, the focus returns to the button
1859
+ * that opened it ("Pay", "Switch to …") from the page or the dialog frame it fell back to, unless the buyer moved it
1860
+ * elsewhere. "Try again" re-asks only for a signature; for a transaction the buyer is sent to the wallet, where the
1861
+ * request still waits, so it cannot be paid twice.
599
1862
  *
600
1863
  * @param props - See {@link WalletPromptProps}.
601
1864
  * @returns The window.
602
1865
  */
603
- declare function WalletPrompt({ kind, walletName, walletId, amount, merchant, network, to, priceTime, onRetry, onCancel, }: WalletPromptProps): react.JSX.Element;
1866
+ declare function WalletPrompt({ kind, walletName, walletId, walletIcon, amount, merchant, network, to, priceTime, onRetry, text, details, hint, onCancel, stepHeight, }: WalletPromptProps): react.JSX.Element;
604
1867
 
605
1868
  /**
606
1869
  * 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 +1874,19 @@ declare function WalletPrompt({ kind, walletName, walletId, amount, merchant, ne
611
1874
  * @returns The value; `undefined` while it is read (or without a key); `null` when the read failed.
612
1875
  */
613
1876
  declare function useAsyncValue<T>(key: string | null, load: () => Promise<T> | T): T | null | undefined;
1877
+ /**
1878
+ * Reads a value like {@link useAsyncValue}, and again when the buyer comes back to the page (focus, visibility) or
1879
+ * `refresh` changes, keeping the last answer meanwhile: a balance the buyer tops up in the wallet opens the pay button
1880
+ * without a reload, and a read under way does not open it before the answer.
1881
+ *
1882
+ * Side effects: `focus` and `visibilitychange` listeners while there is a key.
1883
+ *
1884
+ * @param key - What the value depends on, as a string; `null` to read nothing.
1885
+ * @param load - Reads the value for the current key.
1886
+ * @param refresh - Reads again when it changes, for the same key.
1887
+ * @returns The value; `undefined` until the first answer for this key (or without a key); `null` when the read failed.
1888
+ */
1889
+ declare function useRereadValue<T>(key: string | null, load: () => Promise<T> | T, refresh?: unknown): T | null | undefined;
614
1890
 
615
1891
  /**
616
1892
  * What the parts of the surrounding `PaymentCheckout` share, for components that replace its parts.
@@ -619,6 +1895,39 @@ declare function useAsyncValue<T>(key: string | null, load: () => Promise<T> | T
619
1895
  * @throws When called outside a `PaymentCheckout`.
620
1896
  */
621
1897
  declare function useCheckoutContext(): CheckoutContextValue;
1898
+ /**
1899
+ * The context of the surrounding `PaymentCheckout`, or `null` outside one: for parts the checkout shares with
1900
+ * `RefundButton`, which take the checkout's customization only inside it.
1901
+ *
1902
+ * @returns The checkout context, or `null`.
1903
+ * @internal
1904
+ */
1905
+ declare function useOptionalCheckoutContext(): CheckoutContextValue | null;
1906
+
1907
+ /** Parameters of {@link useCheckoutEvents}. */
1908
+ interface UseCheckoutEventsParams {
1909
+ /** The state of the checkout store. */
1910
+ state: CheckoutState;
1911
+ /** The screen shown. */
1912
+ screen: CheckoutScreen;
1913
+ /** `Date.now()` of the latest second tick of the checkout. */
1914
+ now: number;
1915
+ /** The language the checkout shows; `null` while it is not known yet (the invoice is not read, the app gave none). */
1916
+ locale?: string | null;
1917
+ /** The handlers of `customization.handlers` of `PaymentCheckout`. */
1918
+ handlers?: PaymentCheckoutHandlers;
1919
+ }
1920
+ /**
1921
+ * Tells the app what happened in a checkout through its handlers: `onStatusChange` with the first phase and invoice
1922
+ * status and on every change, `onLocaleShown` with the language shown once it is known and on every change, `onError`
1923
+ * once per new error, and `onExpire` when the locked price runs out (at the
1924
+ * tick that crosses its end) and when the invoice expires, with whether a payment is on its way (one this page handed
1925
+ * over, one of the invoice Quasar reports, as on a reopened page, or one Quasar could not confirm yet and reads again).
1926
+ * Handlers that change between renders are called in their latest version.
1927
+ *
1928
+ * @param params - See {@link UseCheckoutEventsParams}.
1929
+ */
1930
+ declare function useCheckoutEvents({ state, screen, now, locale, handlers }: UseCheckoutEventsParams): void;
622
1931
 
623
1932
  /** What {@link useCheckoutStore} takes. */
624
1933
  interface UseCheckoutStoreOptions {
@@ -632,6 +1941,8 @@ interface UseCheckoutStoreOptions {
632
1941
  EventSource?: EventSourceConstructor | null;
633
1942
  /** How often to read the invoice without an event stream, in milliseconds. */
634
1943
  pollMs?: number;
1944
+ /** Whether to load and follow the invoice; `false` keeps the idle store, which makes no requests. Defaults to `true`. */
1945
+ enabled?: boolean;
635
1946
  }
636
1947
  /**
637
1948
  * The checkout store of an invoice (`createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`): created and loaded
@@ -656,10 +1967,15 @@ declare function useCheckoutState<T>(store: CheckoutStore, selector: (state: Che
656
1967
 
657
1968
  /**
658
1969
  * 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.
1970
+ * `@tuwaio/satellite-react`), in CAIP identifiers, named and shown as the wallet calls itself: the name and icon of
1971
+ * its wallet in the wallet lists of the store (`getConnectors()`, the wallet with exactly the connector type of the
1972
+ * connection), as Nova Connect lists it; `null` without a connection or without the provider, in which case the
1973
+ * checkout offers the QR code and the wallet connection only.
661
1974
  *
662
- * @returns The wallet, or `null`.
1975
+ * Side effects: while mounted in the browser, a subscription to the wallet lists of the store (`watchConnectors` of
1976
+ * `@tuwaio/satellite-core`, when the store has it), so a wallet that announces itself later is named too.
1977
+ *
1978
+ * @returns The wallet, or `null`. The same object while the connection, the name and the icon stay the same.
663
1979
  */
664
1980
  declare function useConnectedWallet(): CheckoutWallet | null;
665
1981
 
@@ -683,6 +1999,55 @@ type NovaPaymentsProviderCustomization = {
683
1999
  transform?: (labels: NovaPaymentsLabels, context: NovaPaymentsLabelsContext) => NovaPaymentsLabels;
684
2000
  };
685
2001
  };
2002
+ /**
2003
+ * The wallet connection Nova brings when the app has no `SatelliteConnectProvider` above {@link NovaPaymentsProvider}:
2004
+ * a Satellite store, its watchers and a Nova Connect modal, all its own. Create it once, at module level: new adapter
2005
+ * objects on every render would be passed to the store again.
2006
+ *
2007
+ * Nova keeps one store per Satellite adapter (the first of `adapter`) for the life of the page, since the wagmi config
2008
+ * and the wallets keep their connections too: a checkout closed and opened again, another page, or a second
2009
+ * `NovaPaymentsProvider` on the same adapters shows the wallet still connected. Nova's part of the package (its
2010
+ * store and the Nova Connect modal) loads on demand, the first time a provider uses its own connection.
2011
+ */
2012
+ interface NovaPaymentsOwnConnection {
2013
+ /**
2014
+ * The Satellite adapters of Nova's store: `satelliteEVMAdapter(wagmiConfig, chains)` of `@tuwaio/satellite-evm`,
2015
+ * `satelliteSolanaAdapter({ rpcUrls })` of `@tuwaio/satellite-solana`.
2016
+ */
2017
+ adapter: SatelliteConnectProviderProps['adapter'];
2018
+ /**
2019
+ * The watchers of that store, which follow the wallets: `<EVMConnectorsWatcher wagmiConfig={wagmiConfig} />` of
2020
+ * `@tuwaio/nova-connect/evm`, `<SolanaConnectorsWatcher />` of `@tuwaio/nova-connect/solana` (without `siwx`).
2021
+ */
2022
+ watchers: ReactNode;
2023
+ /**
2024
+ * The payment adapters, on the same wagmi config as `adapter`: `paymentsEVMAdapter(wagmiConfig)`,
2025
+ * `paymentsSolanaAdapter({ rpcUrls })`.
2026
+ */
2027
+ adapters: PaymentsAdapter[];
2028
+ /**
2029
+ * The props of Nova's own connect modal (`NovaConnectProvider` of `@tuwaio/nova-connect`): `appChains` and/or
2030
+ * `solanaRPCUrls` (the modals are rendered only with them), `labels`, `legal`, `withBalance`… Never `siwx`: Nova's
2031
+ * own connection pays and refunds, it does not sign anyone in.
2032
+ */
2033
+ novaConnect: Omit<NovaConnectProviderPropsWithCustomization, 'children' | 'siwx'>;
2034
+ /**
2035
+ * Whether to reconnect the last wallet after a page load (default `false`). With `true`, Satellite's start-up runs
2036
+ * once per page load (`initializeAutoConnect` of the store): with `@tuwaio/satellite-core` 0.11.1 or later it
2037
+ * reconnects only the last wallet, without a permission prompt, and disconnects only connections this page opened;
2038
+ * 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
2039
+ * `novaConnect.customization` sets `hidden` of `modals.connectModal.childComponents.rememberWallet`.
2040
+ */
2041
+ autoConnect?: boolean;
2042
+ /**
2043
+ * Whether to keep the connected wallet in `localStorage` after the tab closes (default `false`: in `sessionStorage`
2044
+ * until the tab closes). See `rememberWallet` of `createSatelliteConnectStore` from `@tuwaio/satellite-core`. The
2045
+ * keys are shared with every Satellite store of the site: connecting a wallet that is not remembered moves the last
2046
+ * connection out of `localStorage`, and disconnecting removes it, so another Satellite app on the same origin
2047
+ * forgets the wallet it remembered.
2048
+ */
2049
+ rememberWallet?: boolean;
2050
+ }
686
2051
  /** Props of {@link NovaPaymentsProvider}. */
687
2052
  interface NovaPaymentsProviderProps {
688
2053
  /** The Quasar API (Quasar Cloud by default, the address of your node for the Community Edition). */
@@ -692,23 +2057,65 @@ interface NovaPaymentsProviderProps {
692
2057
  /** Customization of the labels. */
693
2058
  customization?: NovaPaymentsProviderCustomization;
694
2059
  /**
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.
2060
+ * The chain families the checkouts pay from the app's connected wallet on: `paymentsEVMAdapter` of
2061
+ * `@tuwaio/nova-payments/evm` (on the wagmi config of the app's Satellite EVM adapter), `paymentsSolanaAdapter` of
2062
+ * `@tuwaio/nova-payments/solana`. Without the adapter of a method's family, the buyer pays that method with a QR
2063
+ * code. When Nova uses its own connection, the `adapters` of `ownConnection` replace them. Without `adapters`, a
2064
+ * provider on the connection of a `NovaPaymentsProvider` above (the app's, or Nova's own) uses the adapters of that
2065
+ * provider; `[]` asks for QR codes only.
698
2066
  */
699
2067
  adapters?: PaymentsAdapter[];
700
2068
  /**
701
- * The app's Pulsar store (`injectExternalPendingTxs` of `createPulsarStore` from `@tuwaio/pulsar-core`). While a
702
- * checkout is open it tracks the payment itself; when it closes before Quasar settled a payment the wallet sent, the
703
- * payment goes to this store, which tracks it and keeps it in the history, and Nova Transactions shows its toast.
2069
+ * The app's Pulsar store (`injectExternalPendingTxs` of `createPulsarStore` from `@tuwaio/pulsar-core`). Every payment
2070
+ * of a checkout goes to it, which tracks it and keeps it in the history, and Nova Transactions shows its toast: one the
2071
+ * wallet sends at once, one the page did not send (a QR code, a relayed signature) once Quasar records it, with its
2072
+ * hash.
704
2073
  */
705
2074
  pulsar?: PaymentsPulsar;
2075
+ /**
2076
+ * The wallet connection Nova brings when the app has none: used only when no `SatelliteConnectProvider` is above
2077
+ * (see {@link NovaPaymentsOwnConnection}). Inside the app's Satellite store, Nova uses the app's connection and never
2078
+ * adds a second one.
2079
+ */
2080
+ ownConnection?: NovaPaymentsOwnConnection;
2081
+ /**
2082
+ * Connects a wallet of a chain family when there is no Nova Connect to open (an app that connects wallets its own
2083
+ * way): the default of every `PaymentCheckout`, `RefundButton` and `RefundDialog` below, which their own
2084
+ * `onConnectWallet` overrides.
2085
+ *
2086
+ * @param family - The chain family of the payment.
2087
+ */
2088
+ onConnectWallet?: (family: PaymentFamily) => void;
706
2089
  /** The app. */
707
2090
  children: ReactNode;
708
2091
  }
709
2092
  /**
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.
2093
+ * Gives the checkouts and refunds below it the Quasar API, the labels, the chain adapters and a wallet connection. A
2094
+ * checkout works without it, with Quasar Cloud, the built-in labels and QR payments only.
2095
+ *
2096
+ * The wallet connection is chosen once, on the first render (see {@link PaymentsConnectionMode} and
2097
+ * {@link usePaymentsConnection}): Nova brings its own connection only when the app has none.
2098
+ *
2099
+ * - Inside the app's `SatelliteConnectProvider` (from `@tuwaio/satellite-react`) and `NovaConnectProvider` (from
2100
+ * `@tuwaio/nova-connect`): the app's wallet, network, connect modal and SIWX, with the `adapters` prop. Nova mounts
2101
+ * nothing of its own.
2102
+ * - Inside the app's Satellite store without Nova Connect: the app's wallet; "Connect wallet" calls `onConnectWallet`.
2103
+ * Nova never adds a second store.
2104
+ * - Without a Satellite store, with `ownConnection`: Nova's own store, watchers and connect modal (never SIWX), with
2105
+ * the adapters of `ownConnection`. It runs Satellite's start-up only when `autoConnect` is set. That part loads on
2106
+ * demand: until it is loaded, nothing below the provider is rendered.
2107
+ * - Without either: QR payments, and `onConnectWallet`.
2108
+ *
2109
+ * A `NovaPaymentsProvider` inside another one's own connection sees that connection as the app's, so two stores never
2110
+ * stack, and without `adapters` it pays with those of the provider above. A later change of the providers above never
2111
+ * remounts the checkouts on another connection.
2112
+ *
2113
+ * Side effects: with its own connection, those of the Satellite store, kept in memory for the life of the page (the
2114
+ * last wallet in `sessionStorage`, or in `localStorage` with `rememberWallet`, under keys shared with every Satellite
2115
+ * store of the site), of the watchers and of Nova Connect. In development (`NODE_ENV` is `development`),
2116
+ * `console.warn` once when the providers above change after the first render, when `ownConnection` is given inside the
2117
+ * app's store without Nova Connect, and when `ownConnection` is given but the app's connection is used without
2118
+ * `adapters` (its own or those of a `NovaPaymentsProvider` above).
712
2119
  *
713
2120
  * @param props - See {@link NovaPaymentsProviderProps}.
714
2121
  * @returns The provider.
@@ -726,8 +2133,20 @@ interface NovaPaymentsProviderProps {
726
2133
  * }
727
2134
  * ```
728
2135
  */
729
- declare function NovaPaymentsProvider({ baseUrl, labels, customization, adapters, pulsar, children, }: NovaPaymentsProviderProps): react.JSX.Element;
2136
+ declare function NovaPaymentsProvider({ baseUrl, labels, customization, adapters, pulsar, ownConnection, onConnectWallet, children, }: NovaPaymentsProviderProps): react.JSX.Element;
730
2137
 
2138
+ /**
2139
+ * Whose wallet connection the checkouts and refunds use, as `NovaPaymentsProvider` decided on its first render:
2140
+ *
2141
+ * - `app`: the app's. A Satellite store (`SatelliteConnectProvider` of `@tuwaio/satellite-react`) and
2142
+ * `NovaConnectProvider` of `@tuwaio/nova-connect` are above it: the wallet, its network, the connect modal and SIWX
2143
+ * are the app's, and Nova adds nothing.
2144
+ * - `appStore`: the app's Satellite store without Nova Connect: "Connect wallet" calls `onConnectWallet`.
2145
+ * - `own`: Nova's own. The app has no Satellite store and gave `ownConnection`: Nova runs its own store, watchers and
2146
+ * connect modal, without SIWX.
2147
+ * - `none`: no connection. The buyer pays with a QR code, or connects through `onConnectWallet`.
2148
+ */
2149
+ type PaymentsConnectionMode = 'app' | 'appStore' | 'own' | 'none';
731
2150
  /** The settings `NovaPaymentsProvider` gives the checkouts below it. */
732
2151
  interface NovaPaymentsSettings {
733
2152
  /** The Quasar API, if set. */
@@ -736,13 +2155,27 @@ interface NovaPaymentsSettings {
736
2155
  labels?: NovaPaymentsLabelOverrides;
737
2156
  /** Customization of the labels. */
738
2157
  customization?: NovaPaymentsProviderCustomization;
739
- /** The chain families the checkouts pay from a connected wallet on. */
2158
+ /**
2159
+ * The chain families the checkouts pay from a connected wallet on: the `adapters` prop, or those of `ownConnection`
2160
+ * when Nova runs its own connection.
2161
+ */
740
2162
  adapters?: PaymentsAdapter[];
741
2163
  /** The app's Pulsar store, which takes over the payments a checkout closed on. */
742
2164
  pulsar?: PaymentsPulsar;
2165
+ /** Whose wallet connection the checkouts use; unset without `NovaPaymentsProvider`. */
2166
+ connection?: PaymentsConnectionMode;
2167
+ /**
2168
+ * The app's handler that connects a wallet, for the checkouts and refunds below without Nova Connect.
2169
+ *
2170
+ * @param family - The chain family of the payment.
2171
+ */
2172
+ onConnectWallet?: (family: PaymentFamily) => void;
743
2173
  }
744
- /** The context of `NovaPaymentsProvider`. @internal */
745
- declare const NovaPaymentsContext: react.Context<NovaPaymentsSettings>;
2174
+ /**
2175
+ * The context of `NovaPaymentsProvider`, created once and saved on `globalThis`
2176
+ * (`Symbol.for('tuwaio.nova-payments.context')`), so copies of the package share it. @internal
2177
+ */
2178
+ declare const NovaPaymentsContext: Context<NovaPaymentsSettings>;
746
2179
 
747
2180
  /**
748
2181
  * The settings of the nearest `NovaPaymentsProvider`; empty without one.
@@ -769,7 +2202,7 @@ declare function useNow(intervalMs: number, active?: boolean): number;
769
2202
  * @param invoice - The invoice of the checkout.
770
2203
  * @param onPaid - The app's callback, if any.
771
2204
  */
772
- declare function usePaidCallback(phase: CheckoutPhase, invoice: CheckoutView['invoice'] | undefined, onPaid: ((invoice: CheckoutView['invoice']) => void) | undefined): void;
2205
+ declare function usePaidCallback(phase: CheckoutPhase, invoice: CheckoutView['invoice'] | undefined, onPaid: ((invoice: CheckoutView['invoice']) => void) | undefined, openedPaid?: boolean): void;
773
2206
  /** What {@link useAutoReturn} needs. */
774
2207
  interface UseAutoReturnParams {
775
2208
  /** Where to send the buyer (the invoice's `successUrl`); `null` for no return. */
@@ -798,6 +2231,111 @@ declare function useAutoReturn({ url, seconds, now, navigate, }: UseAutoReturnPa
798
2231
  stay: () => void;
799
2232
  };
800
2233
 
2234
+ /**
2235
+ * @file Why a wallet did not pay: the buyer declined, the wallet cannot do it, it is on another network, or it failed.
2236
+ */
2237
+ /**
2238
+ * Why a wallet request did not go through: `declined` by the buyer, `unsupported` by the wallet, `wrongNetwork` when it
2239
+ * was on another network than the request, `switchFailed` when it did not switch, `notAuthorized` when it has not allowed
2240
+ * the account for the site (EIP-1193 4100), `alreadyPending` when another request of the site still waits in it,
2241
+ * `sentUnconfirmed` when it sent a payment that is not confirmed yet (it may still land), or `failed`.
2242
+ */
2243
+ type PaymentWalletErrorKind = 'declined' | 'unsupported' | 'wrongNetwork' | 'switchFailed' | 'notAuthorized' | 'alreadyPending' | 'sentUnconfirmed' | 'failed';
2244
+ /** The error a payments adapter throws when it knows why the wallet did not pay. */
2245
+ declare class PaymentWalletError extends Error {
2246
+ readonly kind: PaymentWalletErrorKind;
2247
+ /**
2248
+ * `switch` when the refusal or failure is of the network switch the adapter asked for before the request: the
2249
+ * request itself was never shown (a `declined` one is not a refused signature).
2250
+ */
2251
+ readonly step?: 'switch';
2252
+ /**
2253
+ * @param kind - Why: see {@link PaymentWalletErrorKind}.
2254
+ * @param message - What to log.
2255
+ * @param options - The original error as `cause`, and `step: 'switch'` for a network switch the adapter asked for.
2256
+ */
2257
+ constructor(kind: PaymentWalletErrorKind, message: string, options?: {
2258
+ cause?: unknown;
2259
+ step?: 'switch';
2260
+ });
2261
+ }
2262
+ /**
2263
+ * Why a wallet request failed, from the error the wallet library threw and the causes it wraps, whichever of them names
2264
+ * it: EIP-1193 code `4001` and viem's `UserRejectedRequestError`, and the "user rejected" messages of Wallet Standard
2265
+ * wallets, are `declined`. A request the wallet already has waiting (code `-32002`) is `alreadyPending`, also inside a
2266
+ * failed switch: the buyer answers it there. wagmi's `ChainNotConfiguredError` (the network of the payment is not in the
2267
+ * wagmi config of `paymentsEVMAdapter`; the buyer can still pay with the QR code) and `ConnectorNotConnectedError` (that
2268
+ * config has no connection of the wallet) are `unsupported`, as is a wallet that does not know the request (codes 4200,
2269
+ * -32601, -32004). `ConnectorChainMismatchError` and `ChainMismatchError` are `wrongNetwork`; `SwitchChainError` and
2270
+ * `SwitchChainNotSupportedError` are `switchFailed`; code `4100` is `notAuthorized`. Named apart so that the page never
2271
+ * says a payment failed, or that a fee was spent, about a request that never left the wallet.
2272
+ *
2273
+ * Side effects: in development (`NODE_ENV` is `development`), a failure it cannot name logs to the console, and a
2274
+ * `ConnectorNotConnectedError` logs a `console.error`:
2275
+ * the app gave `NovaPaymentsProvider` an EVM adapter built on another wagmi config than the one its wallet connection
2276
+ * (its Satellite EVM adapter) uses.
2277
+ *
2278
+ * @param error - What the wallet library threw.
2279
+ * @returns The kind.
2280
+ */
2281
+ declare function walletErrorKind(error: unknown): PaymentWalletErrorKind;
2282
+
2283
+ /** Where the confirmation of the paying wallet stands: the wallet switches its network, then signs. */
2284
+ type PayerProofStep = 'idle' | 'switching' | 'signing';
2285
+ /** Why the wallet did not confirm: its kind of failure, or a network switch the buyer refused, no signature being asked. */
2286
+ type PayerProofProblem = PaymentWalletErrorKind | 'switchDeclined';
2287
+ /** What {@link usePayerProof} needs. */
2288
+ interface UsePayerProofParams {
2289
+ /** The adapter of the method's chain family; without `signMessage` the wallet cannot confirm the invoice. */
2290
+ adapter: PaymentsAdapter | undefined;
2291
+ /** The checkout store. */
2292
+ store: {
2293
+ getState: () => Pick<CheckoutState, 'confirmPayer' | 'requestQuote' | 'payer' | 'abandonConfirmation'>;
2294
+ };
2295
+ /** The connected wallet. */
2296
+ wallet: CheckoutWallet | null;
2297
+ /** The CAIP-2 network of the method: a smart wallet's signature counts there only. */
2298
+ chainId: string;
2299
+ }
2300
+ /** What {@link usePayerProof} returns. */
2301
+ interface PayerProofFlow {
2302
+ /** Where the confirmation stands. */
2303
+ step: PayerProofStep;
2304
+ /** Why the wallet did not switch or sign, until the next try; `switchDeclined`: the buyer refused the network switch. */
2305
+ problem: PayerProofProblem | null;
2306
+ /** The message Quasar issued for the wallet to sign (its site, network, nonce), once Quasar answered. */
2307
+ request: PayerProofMessage | null;
2308
+ /**
2309
+ * Confirms the invoice from the wallet: switches the wallet to the method's network when it is on another one, then
2310
+ * has it sign Quasar's message (`confirmPayer` of the checkout store).
2311
+ *
2312
+ * @param options - `quote: true` locks the price once the wallet confirmed (the step before the price).
2313
+ * @param options.quote - Whether to lock the price after it.
2314
+ * @returns Whether the wallet confirmed the invoice.
2315
+ */
2316
+ confirm: (options?: {
2317
+ quote?: boolean;
2318
+ }) => Promise<boolean>;
2319
+ /**
2320
+ * Closes the wallet window. The request stays open in the wallet: a signature it gives later still confirms the
2321
+ * invoice (and locks the price), a refusal is not shown. A cancel during the network switch asks for no signature.
2322
+ * {@link PayerProofFlow.confirm} can be called again at once: the new request replaces the open one, and signing
2323
+ * twice moves no money.
2324
+ */
2325
+ dismiss: () => void;
2326
+ }
2327
+ /**
2328
+ * Confirms that the connected wallet pays the invoice, for the step before the price and for a payment of a method the
2329
+ * gasless relay could pay: a free signature of Quasar's EIP-4361 message that moves no money, one per invoice and wallet.
2330
+ *
2331
+ * Side effects: wallet prompts (a network switch, the signature); `POST payer-proof/message` and `POST payer-proof`
2332
+ * through the checkout store, then `POST quote` with `quote: true`.
2333
+ *
2334
+ * @param params - See {@link UsePayerProofParams}.
2335
+ * @returns See {@link PayerProofFlow}.
2336
+ */
2337
+ declare function usePayerProof({ adapter, store, wallet, chainId }: UsePayerProofParams): PayerProofFlow;
2338
+
801
2339
  /**
802
2340
  * @file The payment of a locked price: how the wallet pays it, what the buyer sends and the merchant receives, the
803
2341
  * market rate behind it, and what a wallet lacks to pay it.
@@ -836,7 +2374,8 @@ interface QuoteAmounts {
836
2374
  } | null;
837
2375
  }
838
2376
  /**
839
- * What the buyer sends and the merchant receives: the same amount, unless the token keeps a fee on every transfer.
2377
+ * What the buyer sends and the merchant receives for this payment: the same amount, unless the token keeps a fee on
2378
+ * every transfer. On the quote of a rest that is what is left of the invoice, not its total.
840
2379
  *
841
2380
  * @param quote - The locked quote.
842
2381
  * @returns The amounts.
@@ -901,6 +2440,12 @@ interface PayInvoiceParams {
901
2440
  paymasterUrl: string | null;
902
2441
  /** Called when the wallet answered, before the payment is handed to Quasar. */
903
2442
  onWalletDone?: () => void;
2443
+ /**
2444
+ * Called with the ID of a sponsored batch as soon as the wallet took it, before it has a transaction.
2445
+ *
2446
+ * @param batchId - The ID of the batch.
2447
+ */
2448
+ onBatchAccepted?: (batchId: string) => void;
904
2449
  /**
905
2450
  * Called with the transaction the wallet sent (its hash), before Quasar takes it; not for a gasless signature, whose
906
2451
  * transaction Quasar sends.
@@ -912,7 +2457,8 @@ interface PayInvoiceParams {
912
2457
  /**
913
2458
  * Pays a locked quote: `transfer` sends the transfer and hands its key to Quasar (`submit`), `relay` signs the
914
2459
  * 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.
2460
+ * to Quasar. A transaction the wallet sent is always handed over, whatever the page shows meanwhile, with the method it
2461
+ * was quoted for: the buyer may have gone on to a price on another network while the wallet asked.
916
2462
  *
917
2463
  * Side effects: a wallet prompt; requests to the checkout routes of Quasar.
918
2464
  *
@@ -921,37 +2467,28 @@ interface PayInvoiceParams {
921
2467
  * @throws {@link PaymentWalletError} `unsupported` when the adapter or the quote cannot take the path; the wallet's
922
2468
  * error when it refuses or fails.
923
2469
  */
924
- declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onSent, }: PayInvoiceParams): Promise<boolean>;
2470
+ declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onBatchAccepted, onSent, }: PayInvoiceParams): Promise<boolean>;
925
2471
 
926
2472
  /**
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`.
2473
+ * How long a request the wallet never answered blocks a second one. A wallet that lost its request (a mobile session that
2474
+ * ended) gives no answer at all, and the buyer must not be trapped by it for good.
947
2475
  *
948
- * @param error - What the wallet library threw.
949
- * @returns `declined`, `unsupported` or `failed`.
2476
+ * @internal
950
2477
  */
951
- declare function walletErrorKind(error: unknown): PaymentWalletErrorKind;
2478
+ declare const OPEN_REQUEST_MS: number;
952
2479
 
953
2480
  /** Where a payment from the wallet stands: `wallet` while the wallet asks the buyer, `submitting` while Quasar takes it. */
954
2481
  type PaymentStatus = 'idle' | 'switching' | 'wallet' | 'submitting';
2482
+
2483
+ /**
2484
+ * Whether the wallet took a sponsored batch of this checkout that has no hash yet: nothing the store knows of, and still the
2485
+ * page must not say that nothing was sent.
2486
+ *
2487
+ * @param store - The checkout store.
2488
+ * @returns Whether such a batch may be on its way.
2489
+ * @internal
2490
+ */
2491
+ declare function isPaymentAccepted(store: object): boolean;
955
2492
  /** What {@link usePayment} needs. */
956
2493
  interface UsePaymentParams {
957
2494
  /** The adapter of the quote's chain family; without it the wallet cannot pay. */
@@ -966,6 +2503,8 @@ interface UsePaymentParams {
966
2503
  path: PayPath;
967
2504
  /** The checkout's ERC-7677 paymaster URL. */
968
2505
  paymasterUrl: string | null;
2506
+ /** The invoice: a sponsored batch the wallet took is kept in the tab under it until its hash comes. */
2507
+ invoiceId?: string;
969
2508
  /**
970
2509
  * Called with the payment the wallet sent (not a gasless signature, whose transaction Quasar sends).
971
2510
  *
@@ -979,6 +2518,10 @@ interface Payment {
979
2518
  status: PaymentStatus;
980
2519
  /** Why the wallet did not pay or switch, until the next try. */
981
2520
  problem: PaymentWalletErrorKind | null;
2521
+ /** The wallet asked, for the window: it keeps its name when the buyer disconnects it while the request waits there. */
2522
+ askedWallet: CheckoutWallet | null;
2523
+ /** What the wallet was asked to send, for the window: a request that waits keeps its amount under a new price. */
2524
+ askedInstructions: PaymentInstructions | null;
982
2525
  /** Pays the quote from the wallet; resolves when Quasar took it or the wallet refused. */
983
2526
  pay: () => Promise<void>;
984
2527
  /** Asks the wallet to switch to the quote's chain. */
@@ -997,30 +2540,52 @@ interface Payment {
997
2540
  * @param params - See {@link UsePaymentParams}.
998
2541
  * @returns See {@link Payment}.
999
2542
  */
1000
- declare function usePayment({ adapter, store, quote, wallet, path, paymasterUrl, onSent }: UsePaymentParams): Payment;
2543
+ declare function usePayment({ adapter, store, quote, wallet, path, paymasterUrl, invoiceId, onSent, }: UsePaymentParams): Payment;
1001
2544
 
2545
+ /** A transfer credited to the invoice, as the paid step lists it. */
2546
+ interface PaymentTransfer {
2547
+ /** The transaction: its hash, or its Solana signature. */
2548
+ txKey: string;
2549
+ /** What it credited with its token (`40.00 USDC`); `null` when Quasar names no token for it. */
2550
+ amount: string | null;
2551
+ /** When the network included it, in milliseconds. */
2552
+ at: number;
2553
+ /** Its page in the explorer of its network, from the chain adapter; `undefined` without one. */
2554
+ explorerUrl: string | undefined;
2555
+ }
1002
2556
  /**
1003
2557
  * What the confirm and paid steps show of the payment: its network and amount (from the locked quote), the
1004
- * transaction (Quasar's hash, else the submitted key) with its explorer link from the chain adapter, and the sender.
2558
+ * transaction (Quasar's hash, else the submitted key) with its explorer link from the chain adapter, the sender, and
2559
+ * every transfer Quasar credited to the invoice (`transfers`, oldest first; empty with a Quasar that does not list
2560
+ * them).
1005
2561
  *
1006
2562
  * @returns The facts; each is `null` (or `undefined` for the link) when unknown.
1007
2563
  */
1008
2564
  declare function usePaymentFacts(): {
1009
2565
  network: string | null;
1010
2566
  amount: string | null;
2567
+ paidAmount: string | null;
1011
2568
  txKey: string | null;
2569
+ lastOfParts: boolean;
2570
+ transfers: PaymentTransfer[];
1012
2571
  explorerUrl: string | undefined;
1013
2572
  from: string | null;
2573
+ fromAddress: string | null;
2574
+ fromUrl: string | undefined;
1014
2575
  };
1015
2576
 
2577
+ /**
2578
+ * The part of the checkout store {@link usePaymentHandOver} reads: the invoice's state, its payment's hash, the price
2579
+ * and the checkout.
2580
+ */
2581
+ type PaymentHandOverState = Pick<CheckoutState, 'invoiceStatus' | 'txHash' | 'quote' | 'checkout'>;
1016
2582
  /** What {@link usePaymentHandOver} needs. */
1017
2583
  interface UsePaymentHandOverParams {
1018
- /** The checkout store (its state is read when the payment is handed over). */
2584
+ /** The checkout store: read when a payment is handed over, and followed for the payments Quasar finds. */
1019
2585
  store: {
1020
- getState: () => Pick<CheckoutState, 'phase' | 'error' | 'checkout'>;
2586
+ getState: () => PaymentHandOverState;
2587
+ subscribe: (listener: (state: PaymentHandOverState, previous: PaymentHandOverState) => void) => () => void;
1021
2588
  };
1022
- /** Whether the checkout is open (a modal); an inline checkout stays open while it is shown. */
1023
- open: boolean;
1024
2589
  /**
1025
2590
  * The adapter of a chain family.
1026
2591
  *
@@ -1036,21 +2601,45 @@ interface UsePaymentHandOverParams {
1036
2601
  locale: string;
1037
2602
  }
1038
2603
  /**
1039
- * Follows the payment the wallet sent until the checkout closes: while it is open the checkout tracks the payment
1040
- * itself; when it closes (or goes away) before Quasar settled the payment, the payment is handed over to the app's
1041
- * Pulsar store, where Nova Transactions shows its toast. A wallet that sends after the checkout closed hands its
1042
- * payment over at once.
2604
+ * Hands the invoice's payments to the app's Pulsar store, where Nova Transactions shows their toasts (owner test
2605
+ * 2026-11-09, finding 3: no toast for any crypto payment, as a payment went over only when the checkout closed before
2606
+ * Quasar settled it). A payment the wallet sends goes over at once, the checkout open or not. A payment the page did not
2607
+ * send (a QR code, a relayed signature, another tab) goes over once Quasar records it, with its hash and the wallet that
2608
+ * paid: only while the page watched the invoice take it, never for an invoice paid before the page opened it, and not
2609
+ * when this page sent a payment of its own (a new hash is a speed-up, which Pulsar's tracker of that payment follows).
2610
+ * Each payment goes over once.
1043
2611
  *
1044
2612
  * Side effects: on hand-over, a pending transaction in the Pulsar store and its tracker.
1045
2613
  *
1046
2614
  * @param params - See {@link UsePaymentHandOverParams}.
1047
2615
  * @returns The function to call with the payment the wallet sent.
1048
2616
  */
1049
- declare function usePaymentHandOver({ store, open, adapterFor, pulsar, labels, locale, }: UsePaymentHandOverParams): (payment: SentPayment) => void;
2617
+ declare function usePaymentHandOver({ store, adapterFor, pulsar, labels, locale, }: UsePaymentHandOverParams): (payment: SentPayment) => void;
2618
+
2619
+ /**
2620
+ * Whose wallet connection the checkouts and refunds use: the choice of the nearest {@link NovaPaymentsProvider}
2621
+ * (made on its first render), or, without one, what the app's providers above give (`app`, `appStore` or `none`). See
2622
+ * {@link PaymentsConnectionMode}.
2623
+ *
2624
+ * @returns The mode.
2625
+ *
2626
+ * @example
2627
+ * ```tsx
2628
+ * import { usePaymentsConnection } from '@tuwaio/nova-payments';
2629
+ *
2630
+ * export function WalletNote() {
2631
+ * const connection = usePaymentsConnection();
2632
+ * return connection === 'own' ? <p>The checkout connects its own wallet.</p> : null;
2633
+ * }
2634
+ * ```
2635
+ */
2636
+ declare function usePaymentsConnection(): PaymentsConnectionMode;
1050
2637
 
1051
2638
  /**
1052
2639
  * 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`.
2640
+ * `NovaPaymentsProvider`, then its `customization.labels.transform`. The built-in labels of a language other than
2641
+ * English load on first use (see `loadLabels`); until they arrive the hook keeps the labels it showed before (English
2642
+ * the first time) and renders again once they are loaded.
1054
2643
  *
1055
2644
  * @param locale - The language of the checkout.
1056
2645
  * @returns The labels.
@@ -1073,15 +2662,17 @@ interface WalletConnection {
1073
2662
  }
1074
2663
  /**
1075
2664
  * 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.
2665
+ * when the checkout is inside `NovaConnectProvider` of `@tuwaio/nova-connect` (the app's, or Nova's own connection of
2666
+ * {@link NovaPaymentsProvider}), else calls the app's handler: `onConnectWallet`, or that of `NovaPaymentsProvider`.
1077
2667
  *
1078
- * @param onConnectWallet - The app's handler, for apps that connect wallets without Nova Connect.
2668
+ * @param onConnectWallet - The app's handler, for apps that connect wallets without Nova Connect; overrides the
2669
+ * `onConnectWallet` of `NovaPaymentsProvider`.
1079
2670
  * @returns See {@link WalletConnection}.
1080
2671
  */
1081
2672
  declare function useWalletConnection(onConnectWallet?: (family: PaymentFamily) => void): WalletConnection;
1082
2673
 
1083
2674
  /**
1084
- * @file The buyer details the checkout collects when the merchant's settings ask for them (plan 12 §6.8): which
2675
+ * @file The buyer details the checkout collects when the merchant's settings ask for them: which
1085
2676
  * fields, what is missing, and the countries to pick from.
1086
2677
  */
1087
2678
 
@@ -1152,7 +2743,7 @@ declare function minorToDecimal(minor: string, digits?: number): string;
1152
2743
  *
1153
2744
  * @param amount - A decimal string or a number.
1154
2745
  * @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.
2746
+ * @returns The formatted amount, for example `1,234.50` in English and `1.234,50` in German.
1156
2747
  */
1157
2748
  declare function formatFiat(amount: string | number, locale: string): string;
1158
2749
  /**
@@ -1165,6 +2756,16 @@ declare function formatFiat(amount: string | number, locale: string): string;
1165
2756
  * @returns The formatted amount, for example `89.54` for `89540000` with 6 decimals.
1166
2757
  */
1167
2758
  declare function formatTokenAmount(baseUnits: string, decimals: number, locale: string): string;
2759
+ /**
2760
+ * 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
2761
+ * (the wallet sets its own and may well charge more), so it has no number.
2762
+ *
2763
+ * @param baseUnits - Base units, as a decimal integer string (not negative).
2764
+ * @param decimals - Decimals of the native token.
2765
+ * @param locale - BCP 47 language of the page.
2766
+ * @returns For example `0.000036` for 36082500481100 with 18 decimals; `null` for a fee below `0.000001`.
2767
+ */
2768
+ declare function formatFeeAmount(baseUnits: string, decimals: number, locale: string): string | null;
1168
2769
  /**
1169
2770
  * A token amount as a wallet takes it when pasted: exact, with a dot, without grouping or trailing zeros.
1170
2771
  *
@@ -1173,17 +2774,10 @@ declare function formatTokenAmount(baseUnits: string, decimals: number, locale:
1173
2774
  * @returns For example `89.54` for `89540000` with 6 decimals, `5` for `5000000`.
1174
2775
  */
1175
2776
  declare function baseUnitsToDecimal(baseUnits: string, decimals: number): string;
2777
+
1176
2778
  /**
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.
2779
+ * Time left as a countdown: `mm:ss` under an hour, `hh:mm:ss` under a day, `Nd hh:mm` beyond, where seconds say nothing
2780
+ * and would not fit beside the date in the summary.
1187
2781
  *
1188
2782
  * @param ms - Milliseconds left; a negative value counts as zero.
1189
2783
  * @returns The countdown.
@@ -1192,7 +2786,7 @@ declare function formatCountdown(ms: number): string;
1192
2786
 
1193
2787
  /**
1194
2788
  * @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.
2789
+ * terms of automatic payments, what an underpaid invoice still needs, and what arrived on an invoice.
1196
2790
  */
1197
2791
 
1198
2792
  /**
@@ -1205,27 +2799,78 @@ declare function formatCountdown(ms: number): string;
1205
2799
  * @returns The link, or `null` when the seller gave neither.
1206
2800
  */
1207
2801
  declare function contactHref(merchant: Pick<CheckoutMerchant, 'supportEmail' | 'website'>, subject: string): string | null;
2802
+ /**
2803
+ * What the checkout says about a payment Quasar ended as failed for good (`payment_failed`), by the reason Quasar gives.
2804
+ * Only a transaction that reverted on the network spent a fee, and only that one is said to have: a transaction whose
2805
+ * time ran out before it landed (`expired`, a Solana blockhash) sent nothing, one the buyer cancelled in the wallet
2806
+ * (`cancelled`) was their own doing, and for anything else (a relay operation that was lost, a cause Quasar does not
2807
+ * name, an older Quasar that gives no reason) the page knows only that the invoice is not paid.
2808
+ *
2809
+ * @param error - The store's `payment_failed` error.
2810
+ * @param labels - The labels of the checkout language.
2811
+ * @param network - The name of the network of the payment, on the pay step; the method step does not know it.
2812
+ * @returns The text.
2813
+ */
2814
+ declare function paymentFailedText(error: CheckoutError, labels: NovaPaymentsLabels, network?: string): string;
2815
+ /**
2816
+ * The transaction of a payment that ended without paying the invoice, when the store's error names one: a transaction
2817
+ * the network has (it reverted, or it succeeded and sent something else), which the page shows with a link to the
2818
+ * explorer next to what it says.
2819
+ *
2820
+ * @param error - The store's error, if any.
2821
+ * @returns The transaction's key, or `null` for any other error, or one that names no transaction.
2822
+ */
2823
+ declare function failedPaymentTx(error: CheckoutError | null | undefined): string | null;
2824
+ /**
2825
+ * What the checkout says about a payment that left the wallet, or may have, from the store's error: a transaction that
2826
+ * does not pay the invoice (`pay.mismatch`; `pay.mismatchTakenElsewhere` when Quasar credited it to another invoice;
2827
+ * `pay.mismatchHeldElsewhere` when another invoice holds it for a refund only, `held`;
2828
+ * `pay.mismatchOtherWallet` for a transfer from a wallet that did not confirm the invoice, `pay.mismatchOtherWalletHeld`
2829
+ * when Quasar recorded it as a held transfer the seller returns, `held`; `pay.mismatchNoReferenceHeld` for a Solana Pay
2830
+ * transfer without the invoice's reference held on this invoice, `held`; `pay.mismatchChargeHeld` for an automatic
2831
+ * charge that landed after the buyer chose another way to pay), a payment Quasar closed after 24 hours without a result on chain
2832
+ * (`outcome.unconfirmedClosed`), a transaction another invoice handed over first (`outcome.unconfirmedTakenElsewhere`)
2833
+ * and a payment the network confirmed that Quasar has not recorded yet (`outcome.unconfirmedSettlementRetrying` while
2834
+ * Quasar settles it again daily, for 30 days, else `outcome.unconfirmedSettlementFailed`). Never "it failed", "only the
2835
+ * network fee was spent" or "nothing was charged" for them.
2836
+ *
2837
+ * @param error - The store's error, if any.
2838
+ * @param labels - The labels of the checkout language.
2839
+ * @param merchant - The seller's name.
2840
+ * @returns The text, or `null` for any other error, or none.
2841
+ */
2842
+ declare function leftTheWalletText(error: CheckoutError | null | undefined, labels: NovaPaymentsLabels, merchant?: string): string | null;
1208
2843
  /**
1209
2844
  * 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.
2845
+ * invoice is settled, the checkout closes without a question; also after a payment that left the wallet, or may have
2846
+ * ({@link leftTheWalletText}: a transaction that does not pay the invoice, a payment Quasar closed without a result on
2847
+ * chain within 24 hours, a transaction another invoice handed over first, a confirmed payment Quasar has not recorded
2848
+ * yet), so the question's "Nothing is sent yet" would not be true. Nor is it on the rest of an underpaid invoice, whose
2849
+ * price stays as it is.
1211
2850
  *
1212
2851
  * @param phase - Where the payment stands.
2852
+ * @param error - The store's last error, if any.
2853
+ * @param status - The state of the invoice, when known.
1213
2854
  * @returns `true` to ask.
1214
2855
  */
1215
- declare function needsLeaveConfirm(phase: CheckoutPhase): boolean;
2856
+ declare function needsLeaveConfirm(phase: CheckoutPhase, error?: CheckoutError | null, status?: string | null): boolean;
1216
2857
  /**
1217
2858
  * The text of a refusal on the method step, with what to do.
1218
2859
  *
1219
2860
  * @param error - The store's error.
1220
2861
  * @param labels - The labels of the checkout language.
2862
+ * @param merchant - The seller's name, for a payment that left the wallet, or may have ({@link leftTheWalletText}).
1221
2863
  * @returns The text.
1222
2864
  */
1223
- declare function methodErrorText(error: CheckoutError, labels: NovaPaymentsLabels): string;
2865
+ declare function methodErrorText(error: CheckoutError, labels: NovaPaymentsLabels, merchant?: string): string;
1224
2866
  /** The terms of an automatic payments offer, as the checkout shows them. */
1225
2867
  interface AutoPayTerms {
1226
2868
  /** The CAIP-2 chain of the charges. */
1227
2869
  chainId: string;
1228
- /** The account that takes the payments (the merchant's collector). */
2870
+ /**
2871
+ * The wallet the charges are paid to: the merchant's, as the `payee` rule of the request names it (the app's
2872
+ * collector, which sends the charges, when the request names no payee).
2873
+ */
1229
2874
  to: string;
1230
2875
  /** The most it takes in a period, in base units of the token. */
1231
2876
  limit: string;
@@ -1238,9 +2883,20 @@ interface AutoPayTerms {
1238
2883
  /** When the permission ends, in milliseconds; `null` without an expiry rule. */
1239
2884
  expiresAt: number | null;
1240
2885
  }
2886
+ /**
2887
+ * What the connected wallet may ask its wallet for: the offer, or taking over an active permission that holds nothing.
2888
+ *
2889
+ * @param offer - The automatic-charge offer of the checkout.
2890
+ * @returns The method and the request, or `null` when nothing can be given now.
2891
+ */
2892
+ declare function grantableOffer(offer: AutoChargeOffer | null): Extract<AutoChargeOffer, {
2893
+ status: 'available';
2894
+ }> | NonNullable<Extract<AutoChargeOffer, {
2895
+ status: 'active';
2896
+ }>['replacement']> | null;
1241
2897
  /**
1242
2898
  * 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.
2899
+ * expiry and the merchant's wallet the charges are paid to.
1244
2900
  *
1245
2901
  * @param offer - The view's `autoCharge`.
1246
2902
  * @param methods - The view's methods (for the token of the offer).
@@ -1263,6 +2919,142 @@ declare function formatPeriod(seconds: number, locale: string): string;
1263
2919
  * @returns The rest, or `null` when it is unknown or nothing is left.
1264
2920
  */
1265
2921
  declare function underpaidRest(quote: Pick<CheckoutQuote, 'cryptoAmountExpected'> | null, amountPaid: string | null): string | null;
2922
+ /**
2923
+ * What the buyer is told about the rate of the rest of an underpaid invoice, in an asset that moves against the invoice
2924
+ * currency (`rateHeldUntil` of the quote): until when a payment settles by itself, or that the seller now decides.
2925
+ *
2926
+ * @param quote - The locked quote.
2927
+ * @param now - The time now, in milliseconds.
2928
+ * @param labels - The labels of the checkout language.
2929
+ * @param merchant - The seller's name.
2930
+ * @param locale - The language of the checkout.
2931
+ * @param ended - What is said past that time; the payment step's `pay.restRateEnded` speaks of the payment being made.
2932
+ * @returns The text, or `null` when the rate holds until the due date.
2933
+ */
2934
+ declare function restRateText(quote: Pick<CheckoutQuote, 'rateHeldUntil'> | null, now: number, labels: NovaPaymentsLabels, merchant: string, locale: string, ended?: string): string | null;
2935
+ /**
2936
+ * The address of a wallet Quasar names: it keeps the wallet that paid first as an address or as a CAIP-10 account.
2937
+ *
2938
+ * @param wallet - The wallet, in either form.
2939
+ * @returns The address.
2940
+ */
2941
+ declare function addressOfWallet(wallet: string): string;
2942
+ /**
2943
+ * Whether two wallets Quasar names are one: an EVM address in any letter case, any other exactly.
2944
+ *
2945
+ * @param a - A wallet, as an address or an account.
2946
+ * @param b - Another one.
2947
+ * @returns `true` for the same wallet.
2948
+ */
2949
+ declare function isSameWallet(a: string, b: string): boolean;
2950
+ /**
2951
+ * What arrived on an invoice, when anything did: an expired invoice says so instead of "nothing was charged".
2952
+ *
2953
+ * @param amountPaid - What arrived, in base units of the locked token (`amountPaid` of the invoice).
2954
+ * @returns The amount, or `null` when nothing arrived.
2955
+ */
2956
+ declare function receivedAmount(amountPaid: string | null): string | null;
2957
+ /**
2958
+ * 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
2959
+ * percent or more, so a stablecoin at par never asks.
2960
+ *
2961
+ * @param preview - What the refund would send.
2962
+ * @returns Whether the merchant should look first.
2963
+ */
2964
+ declare function refundRateMoved(preview: Pick<RefundPreview, 'cryptoAmount' | 'atPaymentRate'> & Partial<Pick<RefundPreview, 'received'>>): boolean;
2965
+ /**
2966
+ * Whether the checkout needs its second tick: for the deadline, the price lock and the return countdown. A receipt or an
2967
+ * expired page left open would otherwise render everything once a second for nothing.
2968
+ *
2969
+ * @param phase - The checkout's phase.
2970
+ * @param autoReturnSeconds - The seconds before the paid outcome returns to the seller, when set.
2971
+ * @param labelsShown - Whether the labels of the language are there: their file shows with a render.
2972
+ * @returns Whether to tick.
2973
+ * @internal
2974
+ */
2975
+ declare function needsTheClock(phase: string, autoReturnSeconds: number | undefined, labelsShown: boolean): boolean;
2976
+
2977
+ /**
2978
+ * @file The paying wallet's confirmation of the invoice: before an EVM payment the buyer's
2979
+ * wallet sends itself, it signs Quasar's message for free, so that Quasar credits its transfers to this invoice only.
2980
+ * When the checkout asks for it, what it says about a refusal, and which wallets sign with a passkey.
2981
+ */
2982
+
2983
+ /** Why the wallet did not confirm: its kind of failure, or a network switch the buyer refused. */
2984
+ type ConfirmProblem = PaymentWalletErrorKind | 'switchDeclined';
2985
+ /**
2986
+ * Whether the wallet is a smart account that signs with a passkey (or a fingerprint), by its connector type.
2987
+ *
2988
+ * @param wallet - The connected wallet.
2989
+ * @returns `true` for Coinbase Smart Wallet, Base Account and Porto.
2990
+ */
2991
+ declare function isSmartWallet(wallet: Pick<CheckoutWallet, 'connectorType'> | null | undefined): boolean;
2992
+ /**
2993
+ * Whether the wallet confirms the invoice before it pays from the pay step: while the checkout store says it must
2994
+ * (`required`, `confirming`), and for a method the gasless relay could pay (`unless_relayed`) when the wallet sends the
2995
+ * transfer or the paymaster's calls itself; the relay's signed authorization confirms the wallet on its own.
2996
+ *
2997
+ * @param payerProof - `payerProof` of the checkout store (left out by older stores).
2998
+ * @param path - How the wallet pays the quote.
2999
+ * @returns `true` to ask for the confirmation first.
3000
+ */
3001
+ declare function needsPayerProof(payerProof: string | undefined, path: PayPath): boolean;
3002
+ /** The part of the checkout store {@link lockPrice} reads. */
3003
+ interface LockPriceStore {
3004
+ /** The store's state and actions. */
3005
+ getState: () => Pick<CheckoutState, 'requestQuote' | 'error'> & {
3006
+ readonly payerProof?: string;
3007
+ };
3008
+ }
3009
+ /**
3010
+ * Locks the price for the wallet the buyer continued with, or turns to the step that confirms the wallet first: while
3011
+ * the checkout store says the wallet must confirm the invoice (`payerProof` `required`), no price is asked; when Quasar
3012
+ * refuses the price with `payer_proof_required` (a wallet it wants confirmed, which the checkout did not announce), the
3013
+ * step shows too.
3014
+ *
3015
+ * Side effects: `POST quote` through the checkout store.
3016
+ *
3017
+ * @param store - The checkout store.
3018
+ * @param showConfirmWallet - Shows (`true`) or leaves (`false`) the step that confirms the wallet.
3019
+ * @returns The quote, or `null` when none was locked.
3020
+ */
3021
+ declare function lockPrice(store: LockPriceStore, showConfirmWallet: (show: boolean) => void): Promise<CheckoutQuote | null>;
3022
+ /**
3023
+ * Whether the error is a refusal of the wallet's confirmation (`payer_proof_*`, `payer_chain_mismatch`,
3024
+ * `too_many_payers`): the pay step shows only these under the confirmation, its other errors have texts of their own.
3025
+ *
3026
+ * @param error - The checkout store's error, if any.
3027
+ * @returns `true` for a refusal of the confirmation.
3028
+ */
3029
+ declare function isPayerProofError(error: CheckoutError | null | undefined): boolean;
3030
+ /**
3031
+ * Whether an error belongs on the step that confirms the wallet. The store's error may be about something else: a
3032
+ * transfer held from another wallet, or a price refused to the last wallet, opened the step with "Something went wrong"
3033
+ * before the wallet was asked anything.
3034
+ *
3035
+ * @param error - The checkout store's error, if any.
3036
+ * @returns `true` for a refusal of the confirmation or a failure of its requests.
3037
+ */
3038
+ declare function isConfirmationError(error: CheckoutError | null | undefined): boolean;
3039
+ /**
3040
+ * What the step that confirms the wallet says about a refusal, with what to do: the wallet's (the buyer declined, the
3041
+ * wallet cannot sign messages, it failed) or Quasar's (`payer_proof_invalid`, `payer_proof_unavailable`,
3042
+ * `payer_chain_mismatch`, `too_many_payers`, `rate_limited`…). The buyer stays on the step and can try again.
3043
+ *
3044
+ * @param error - The checkout store's error, if any.
3045
+ * @param problem - Why the wallet did not sign, when the checkout knows it.
3046
+ * @param labels - The labels of the checkout language.
3047
+ * @param values - The wallet's name, the method's network and the seller's name.
3048
+ * @param values.wallet - The wallet's name.
3049
+ * @param values.network - The network of the method.
3050
+ * @param values.merchant - The seller's name.
3051
+ * @returns The text, or `null` with nothing to say (no error, or `payer_proof_required`, the reason the step shows).
3052
+ */
3053
+ declare function payerProofErrorText(error: CheckoutError | null | undefined, problem: ConfirmProblem | null, labels: NovaPaymentsLabels, values: {
3054
+ wallet: string;
3055
+ network: string;
3056
+ merchant: string;
3057
+ }): string | null;
1266
3058
 
1267
3059
  /**
1268
3060
  * @file A QR code as one SVG path, so the checkout draws it in its own colors.
@@ -1279,6 +3071,21 @@ declare function qrPath(text: string): {
1279
3071
  path: string;
1280
3072
  };
1281
3073
 
3074
+ /**
3075
+ * @file A refund as the merchant's wallet sends it: the transfer Quasar asks for, in the shape of a payment.
3076
+ */
3077
+
3078
+ /** What Quasar asks the merchant to send for a refund (`instructions` of the refund store). */
3079
+ type RefundInstructions = NonNullable<RefundState['instructions']>;
3080
+ /**
3081
+ * The transfer of a refund as a payments adapter sends it (`sendTransfer`): the asset of the payment to the payer, on
3082
+ * the chain of the payment. The token is the contract or mint of the CAIP-19 asset, `native` for the coin of the chain.
3083
+ *
3084
+ * @param instructions - What Quasar asks to send.
3085
+ * @returns The transfer, or `null` without a recipient or on a chain no adapter pays on.
3086
+ */
3087
+ declare function refundTransfer(instructions: RefundInstructions): PaymentInstructions | null;
3088
+
1282
3089
  /**
1283
3090
  * Subtotal and tax of the invoice from its lines: the lines carry net amounts, the total includes tax. The tax row
1284
3091
  * shows the rate when all taxed lines share one.
@@ -1293,4 +3100,5 @@ declare function invoiceTotals(invoice: CheckoutView['invoice']): {
1293
3100
  total: string;
1294
3101
  };
1295
3102
 
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 };
3103
+ export { AmountStep, AutoPayScreen, BuyerScreen, CheckoutContext, CheckoutContextProvider, CheckoutFrame, CheckoutHeader, CheckoutPageRoot, CheckoutStepper, CheckoutSummary, CheckoutWallet, CompactSummary, ConfirmScreen, ConfirmStep, ConfirmWalletScreen, ContactLink, DEADLINE_ANNOUNCEMENTS, DeadlineTimer, Disclosure, FailedScreen, 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, failedPaymentTx, 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, paymentFailedText, qrPath, quoteAmounts, quoteRate, receivedAmount, refundRateMoved, refundTransfer, refusalText, restRateText, screensPayingWallets, sentBeforeDeadline, shownLocale, 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 };
3104
+ 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, PaymentHandOverState, PaymentStatus, PaymentTransfer, PaymentWalletErrorKind, PaymentsConnectionMode, PaymentsPulsar, QuoteAmounts, RefundButtonProps, RefundDialogProps, RefundFlow, RefundInstructions, RefundProblem, RefundRequest, RefundStep, SentBeforeDeadlineParams, SentPayment, UnconfirmedFollowUp, UseAutoReturnParams, UseCheckoutEventsParams, UseCheckoutStoreOptions, UsePayerProofParams, UsePaymentHandOverParams, UsePaymentParams, UseRefundParams, WalletConnection, WalletPromptKind, WalletPromptProps };