@tuwaio/nova-payments 0.0.1 → 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 (47) hide show
  1. package/README.md +10 -5
  2. package/dist/chunk-7FQXTBOY.cjs +1 -0
  3. package/dist/chunk-7HSDAUKN.js +1 -0
  4. package/dist/chunk-EMYW4LI7.js +1 -0
  5. package/dist/chunk-HRTXVGBJ.cjs +1 -0
  6. package/dist/de-DXFDX3GR.js +1 -0
  7. package/dist/de-TJ6BGSUG.cjs +1 -0
  8. package/dist/es-DCARFZ3R.js +1 -0
  9. package/dist/es-I4V64VEP.cjs +1 -0
  10. package/dist/evm/index.cjs +1 -1
  11. package/dist/evm/index.d.cts +13 -5
  12. package/dist/evm/index.d.ts +13 -5
  13. package/dist/evm/index.js +1 -1
  14. package/dist/i18n/index.cjs +1 -1
  15. package/dist/i18n/index.d.cts +2 -2
  16. package/dist/i18n/index.d.ts +2 -2
  17. package/dist/i18n/index.js +1 -1
  18. package/dist/index.cjs +2 -2
  19. package/dist/index.css +198 -47
  20. package/dist/index.d.cts +174 -48
  21. package/dist/index.d.ts +174 -48
  22. package/dist/index.js +2 -2
  23. package/dist/it-N36S2FXH.js +1 -0
  24. package/dist/it-RQJGHQPP.cjs +1 -0
  25. package/dist/{locales-DzMinYsr.d.cts → locales-DP2jStIs.d.cts} +66 -5
  26. package/dist/{locales-DzMinYsr.d.ts → locales-DP2jStIs.d.ts} +66 -5
  27. package/dist/solana/index.cjs +1 -1
  28. package/dist/solana/index.js +1 -1
  29. package/dist/uk-FFP4RBO4.js +1 -0
  30. package/dist/uk-HYM26VN5.cjs +1 -0
  31. package/dist/zhCN-EKUFCQTZ.js +1 -0
  32. package/dist/zhCN-Q5DO4HXO.cjs +1 -0
  33. package/package.json +10 -11
  34. package/dist/chunk-PUMIYLSN.js +0 -1
  35. package/dist/chunk-S3L4QDPT.cjs +0 -1
  36. package/dist/chunk-WOAPFVQF.js +0 -1
  37. package/dist/chunk-XOVRZTAM.cjs +0 -1
  38. package/dist/de-53SSE6O2.js +0 -1
  39. package/dist/de-LB5XSRMX.cjs +0 -1
  40. package/dist/es-LP3HJ4KB.js +0 -1
  41. package/dist/es-VDW2RZMP.cjs +0 -1
  42. package/dist/it-6IQFXLAR.cjs +0 -1
  43. package/dist/it-JJ5Z5EUF.js +0 -1
  44. package/dist/uk-EI4N5BMM.js +0 -1
  45. package/dist/uk-FVCYLYSB.cjs +0 -1
  46. package/dist/zhCN-BZBMKUUA.js +0 -1
  47. package/dist/zhCN-TA7WU5XS.cjs +0 -1
package/dist/index.d.cts CHANGED
@@ -50,9 +50,10 @@ declare function BuyerScreen(): react.JSX.Element | null;
50
50
  /**
51
51
  * A screen of the checkout: the steps of a payment (`buyer`, `method`, `confirmWallet` — the paying wallet confirms the
52
52
  * invoice with a free signature before the price —, `pay` or `qr`, `confirm`, `autoPay`), a payment Quasar could not
53
- * confirm (`unconfirmed`: it may still arrive, so the buyer checks the wallet before paying again) or its outcome.
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.
54
55
  */
55
- type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'confirmWallet' | 'pay' | 'qr' | 'confirm' | 'unconfirmed' | 'paid' | 'autoPay' | 'autoPayOff' | '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';
56
57
  /** Choices of the buyer that the checkout store does not hold. */
57
58
  interface CheckoutScreenChoices {
58
59
  /** Pay from a wallet in this browser (default) or scan a QR code with a phone. */
@@ -77,6 +78,11 @@ interface CheckoutScreenChoices {
77
78
  * after it.
78
79
  */
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;
80
86
  }
81
87
  /**
82
88
  * Whether the permission screen can open from this phase: another wallet takes over a permission from the steps before a
@@ -134,8 +140,8 @@ declare function checkoutSteps(screen: CheckoutScreen, options?: {
134
140
  withDetails?: boolean;
135
141
  }): CheckoutStep[] | null;
136
142
  /**
137
- * The steps of the stepper on the paid screen of a payment page, all done. Elsewhere that screen has no stepper
138
- * ({@link checkoutSteps}).
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).
139
145
  *
140
146
  * @param options - Steps that apply to this invoice.
141
147
  * @param options.withDetails - The checkout asked for the buyer details first.
@@ -402,13 +408,34 @@ declare function unconfirmedFollowUp(error: CheckoutError | null | undefined): U
402
408
  declare function unconfirmedTxKey(state: Pick<CheckoutState, 'txKey' | 'txHash'> & {
403
409
  error?: object | null;
404
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;
405
432
 
406
433
  /**
407
- * @file Handing a payment the wallet sent over to the app's Pulsar store when the checkout closes before Quasar
408
- * 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.
409
436
  */
410
437
 
411
- /** 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. */
412
439
  interface SentPayment {
413
440
  /** The transaction hash (EVM) or signature (Solana). */
414
441
  txKey: string;
@@ -432,20 +459,6 @@ interface PaymentsPulsar {
432
459
  */
433
460
  injectExternalPendingTxs(transactions: Transaction[]): Promise<void>;
434
461
  }
435
- /**
436
- * Whether a sent payment still needs tracking when the checkout closes: Quasar has not settled it, and it did not
437
- * fail on-chain or turn out not to pay the invoice.
438
- *
439
- * @param state - The `phase` and `error` of the checkout store.
440
- * @param state.phase - Where the payment stands.
441
- * @param state.error - The last failure; `payment_failed` means the transaction failed on-chain, `payment_mismatch`
442
- * that it succeeded without paying the invoice: Quasar already has the final word on both.
443
- * @returns `true` to hand it over.
444
- */
445
- declare function shouldHandOver(state: {
446
- phase: CheckoutPhase;
447
- error: CheckoutError | null;
448
- }): boolean;
449
462
  /** What {@link handOverPayment} needs. */
450
463
  interface HandOverParams {
451
464
  /** The adapter of the payment's chain family. */
@@ -529,6 +542,8 @@ declare function CheckoutStepper({ steps, labels, className, stepClassName }: Ch
529
542
 
530
543
  /** The outcomes this screen shows. */
531
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;
532
547
  /**
533
548
  * An outcome other than paid: a payment Quasar could not confirm (`unconfirmed`: it may still arrive, so the buyer
534
549
  * checks the wallet before paying again; only while Quasar still reads it again, `error.rechecked` of the checkout
@@ -756,6 +771,16 @@ interface PaymentCheckoutClassNames {
756
771
  statusIcon?: (params: CheckoutPartState & {
757
772
  kind: OutcomeKind;
758
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;
759
784
  /**
760
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.
761
786
  *
@@ -896,6 +921,19 @@ interface PaymentCheckoutHandlers {
896
921
  locale: CheckoutLocale;
897
922
  proceed: () => Promise<void>;
898
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;
899
937
  /**
900
938
  * The phase of the checkout or the status of the invoice changed; also called once with the first ones.
901
939
  *
@@ -1058,6 +1096,13 @@ interface PaymentCheckoutProps {
1058
1096
  autoReturnSeconds?: number;
1059
1097
  /** Replaces the link of "Contact <seller>" (the seller's support email, else site) with the app's own handler. */
1060
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;
1061
1106
  /** Classes added to the checkout block. */
1062
1107
  className?: string;
1063
1108
  /**
@@ -1113,7 +1158,7 @@ declare function CheckoutFrame({ className, withDetails, leave, }: {
1113
1158
  * }
1114
1159
  * ```
1115
1160
  */
1116
- declare function PaymentCheckout({ token, display, open, onOpenChange, onClose, baseUrl, api, EventSource, pollMs, payUrl, onConnectWallet, onPaid, autoReturnSeconds, onContact, className, customization, }: PaymentCheckoutProps): react.JSX.Element;
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;
1117
1162
  /**
1118
1163
  * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1119
1164
  * no step can move its top.
@@ -1140,6 +1185,14 @@ interface CheckoutContextValue {
1140
1185
  locale: string;
1141
1186
  /** The labels of that language. */
1142
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>;
1143
1196
  /** `Date.now()` of the latest second tick. */
1144
1197
  now: number;
1145
1198
  /**
@@ -1201,6 +1254,11 @@ interface CheckoutContextValue {
1201
1254
  setHandoff: (handoff: boolean) => void;
1202
1255
  /** Goes back to the method step: forgets the locked price and the phone hand-off. */
1203
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;
1204
1262
  /**
1205
1263
  * Whether the buyer continued with a wallet that must confirm the invoice before the price: the step that confirms
1206
1264
  * it shows while the checkout store waits for the signature (`ConfirmWalletScreen`).
@@ -1220,8 +1278,8 @@ interface CheckoutContextValue {
1220
1278
  */
1221
1279
  lockPrice: () => Promise<void>;
1222
1280
  /**
1223
- * Remembers the payment the wallet sent: the checkout tracks it while open, and hands it over to the app's Pulsar
1224
- * store when it closes before Quasar settled it.
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.
1225
1283
  *
1226
1284
  * @param payment - The transaction and what it pays.
1227
1285
  */
@@ -1322,9 +1380,10 @@ declare function CompactSummary({ className }?: {
1322
1380
  }): react.JSX.Element | null;
1323
1381
 
1324
1382
  /**
1325
- * The confirm step: the transaction is on its way and Quasar follows it until it is final. It reuses the status and
1326
- * progress of Nova Transactions (Sent → Confirming → Paid, in the language of the checkout) and shows the network, the
1327
- * amount, the transaction with its explorer link and the sender. The buyer may close the window: the payment keeps
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
1328
1387
  * going. It also shows a payment of the invoice that this page did not hand over while Quasar reports it on its way
1329
1388
  * (the page was reopened or reloaded, another tab paid, Quasar found a Solana Pay transfer), instead of offering to pay
1330
1389
  * again: its note asks the buyer to wait for it. When the invoice deadline passes while a payment is on its way (the
@@ -1361,6 +1420,18 @@ declare function ConfirmScreen(): react.JSX.Element;
1361
1420
  */
1362
1421
  declare function ConfirmWalletScreen(): react.JSX.Element | null;
1363
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
+
1364
1435
  /**
1365
1436
  * The question when the buyer closes the checkout before anything is sent: the invoice stays open until its deadline,
1366
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
@@ -1424,7 +1495,8 @@ declare function LocaleSwitcher({ locale, labels, receiptIssued, onSelect, class
1424
1495
  declare function MethodScreen(): react.JSX.Element | null;
1425
1496
 
1426
1497
  /**
1427
- * The paid outcome: the amount, network, time and transaction, the steps done, a refund made later, the receipt to
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
1428
1500
  * download, the automatic payments offer of a subscription, and the way back to the seller (`successUrl`) with a
1429
1501
  * visible countdown and "Stay here" (WCAG 2.2.1). In a modal it offers Close instead: the page under it is the
1430
1502
  * seller's, and loading it again would close everything at once.
@@ -1840,19 +1912,22 @@ interface UseCheckoutEventsParams {
1840
1912
  screen: CheckoutScreen;
1841
1913
  /** `Date.now()` of the latest second tick of the checkout. */
1842
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;
1843
1917
  /** The handlers of `customization.handlers` of `PaymentCheckout`. */
1844
1918
  handlers?: PaymentCheckoutHandlers;
1845
1919
  }
1846
1920
  /**
1847
1921
  * Tells the app what happened in a checkout through its handlers: `onStatusChange` with the first phase and invoice
1848
- * status and on every change, `onError` once per new error, and `onExpire` when the locked price runs out (at the
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
1849
1924
  * tick that crosses its end) and when the invoice expires, with whether a payment is on its way (one this page handed
1850
1925
  * over, one of the invoice Quasar reports, as on a reopened page, or one Quasar could not confirm yet and reads again).
1851
1926
  * Handlers that change between renders are called in their latest version.
1852
1927
  *
1853
1928
  * @param params - See {@link UseCheckoutEventsParams}.
1854
1929
  */
1855
- declare function useCheckoutEvents({ state, screen, now, handlers }: UseCheckoutEventsParams): void;
1930
+ declare function useCheckoutEvents({ state, screen, now, locale, handlers }: UseCheckoutEventsParams): void;
1856
1931
 
1857
1932
  /** What {@link useCheckoutStore} takes. */
1858
1933
  interface UseCheckoutStoreOptions {
@@ -1991,9 +2066,10 @@ interface NovaPaymentsProviderProps {
1991
2066
  */
1992
2067
  adapters?: PaymentsAdapter[];
1993
2068
  /**
1994
- * The app's Pulsar store (`injectExternalPendingTxs` of `createPulsarStore` from `@tuwaio/pulsar-core`). While a
1995
- * checkout is open it tracks the payment itself; when it closes before Quasar settled a payment the wallet sent, the
1996
- * 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.
1997
2073
  */
1998
2074
  pulsar?: PaymentsPulsar;
1999
2075
  /**
@@ -2168,13 +2244,19 @@ type PaymentWalletErrorKind = 'declined' | 'unsupported' | 'wrongNetwork' | 'swi
2168
2244
  /** The error a payments adapter throws when it knows why the wallet did not pay. */
2169
2245
  declare class PaymentWalletError extends Error {
2170
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';
2171
2252
  /**
2172
2253
  * @param kind - Why: see {@link PaymentWalletErrorKind}.
2173
2254
  * @param message - What to log.
2174
- * @param options - The original error as `cause`.
2255
+ * @param options - The original error as `cause`, and `step: 'switch'` for a network switch the adapter asked for.
2175
2256
  */
2176
2257
  constructor(kind: PaymentWalletErrorKind, message: string, options?: {
2177
2258
  cause?: unknown;
2259
+ step?: 'switch';
2178
2260
  });
2179
2261
  }
2180
2262
  /**
@@ -2460,9 +2542,22 @@ interface Payment {
2460
2542
  */
2461
2543
  declare function usePayment({ adapter, store, quote, wallet, path, paymasterUrl, invoiceId, onSent, }: UsePaymentParams): Payment;
2462
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
+ }
2463
2556
  /**
2464
2557
  * What the confirm and paid steps show of the payment: its network and amount (from the locked quote), the
2465
- * 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).
2466
2561
  *
2467
2562
  * @returns The facts; each is `null` (or `undefined` for the link) when unknown.
2468
2563
  */
@@ -2472,20 +2567,25 @@ declare function usePaymentFacts(): {
2472
2567
  paidAmount: string | null;
2473
2568
  txKey: string | null;
2474
2569
  lastOfParts: boolean;
2570
+ transfers: PaymentTransfer[];
2475
2571
  explorerUrl: string | undefined;
2476
2572
  from: string | null;
2477
2573
  fromAddress: string | null;
2478
2574
  fromUrl: string | undefined;
2479
2575
  };
2480
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'>;
2481
2582
  /** What {@link usePaymentHandOver} needs. */
2482
2583
  interface UsePaymentHandOverParams {
2483
- /** 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. */
2484
2585
  store: {
2485
- getState: () => Pick<CheckoutState, 'phase' | 'error' | 'checkout'>;
2586
+ getState: () => PaymentHandOverState;
2587
+ subscribe: (listener: (state: PaymentHandOverState, previous: PaymentHandOverState) => void) => () => void;
2486
2588
  };
2487
- /** Whether the checkout is open (a modal); an inline checkout stays open while it is shown. */
2488
- open: boolean;
2489
2589
  /**
2490
2590
  * The adapter of a chain family.
2491
2591
  *
@@ -2501,17 +2601,20 @@ interface UsePaymentHandOverParams {
2501
2601
  locale: string;
2502
2602
  }
2503
2603
  /**
2504
- * Follows the payment the wallet sent until the checkout closes: while it is open the checkout tracks the payment
2505
- * itself; when it closes (or goes away) before Quasar settled the payment, the payment is handed over to the app's
2506
- * Pulsar store, where Nova Transactions shows its toast. A wallet that sends after the checkout closed hands its
2507
- * 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.
2508
2611
  *
2509
2612
  * Side effects: on hand-over, a pending transaction in the Pulsar store and its tracker.
2510
2613
  *
2511
2614
  * @param params - See {@link UsePaymentHandOverParams}.
2512
2615
  * @returns The function to call with the payment the wallet sent.
2513
2616
  */
2514
- 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;
2515
2618
 
2516
2619
  /**
2517
2620
  * Whose wallet connection the checkouts and refunds use: the choice of the nearest {@link NovaPaymentsProvider}
@@ -2696,13 +2799,36 @@ declare function formatCountdown(ms: number): string;
2696
2799
  * @returns The link, or `null` when the seller gave neither.
2697
2800
  */
2698
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;
2699
2824
  /**
2700
2825
  * What the checkout says about a payment that left the wallet, or may have, from the store's error: a transaction that
2701
2826
  * does not pay the invoice (`pay.mismatch`; `pay.mismatchTakenElsewhere` when Quasar credited it to another invoice;
2702
2827
  * `pay.mismatchHeldElsewhere` when another invoice holds it for a refund only, `held`;
2703
2828
  * `pay.mismatchOtherWallet` for a transfer from a wallet that did not confirm the invoice, `pay.mismatchOtherWalletHeld`
2704
- * when Quasar recorded it as a held transfer the seller returns, `held`; `pay.mismatchChargeHeld` for an automatic charge
2705
- * that landed after the buyer chose another way to pay), a payment Quasar closed after 24 hours without a result on chain
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
2706
2832
  * (`outcome.unconfirmedClosed`), a transaction another invoice handed over first (`outcome.unconfirmedTakenElsewhere`)
2707
2833
  * and a payment the network confirmed that Quasar has not recorded yet (`outcome.unconfirmedSettlementRetrying` while
2708
2834
  * Quasar settles it again daily, for 30 days, else `outcome.unconfirmedSettlementFailed`). Never "it failed", "only the
@@ -2974,5 +3100,5 @@ declare function invoiceTotals(invoice: CheckoutView['invoice']): {
2974
3100
  total: string;
2975
3101
  };
2976
3102
 
2977
- export { AmountStep, AutoPayScreen, BuyerScreen, CheckoutContext, CheckoutContextProvider, CheckoutFrame, CheckoutHeader, CheckoutPageRoot, CheckoutStepper, CheckoutSummary, CheckoutWallet, CompactSummary, ConfirmScreen, ConfirmStep, ConfirmWalletScreen, DEADLINE_ANNOUNCEMENTS, DeadlineTimer, Disclosure, FailedStep, LeaveDialog, LocaleSwitcher, MerchantBadge, MethodScreen, MobileSteps, NativeFee, NovaPaymentsContext, NovaPaymentsProvider, OPEN_REQUEST_MS, OrderLines, OrderTotal, OutcomeScreen, PaidScreen, PayScreen, PaymentCheckout, PaymentFamily, PaymentWalletError, PaymentsAdapter, QUOTE_WARNING_MS, QrScreen, RefundButton, RefundDialog, RefundSteps, ScreenBody, SellerDetailsContent, SummaryFooter, WalletPrompt, addressOfWallet, autoPayTerms, balanceShortfall, baseUnitsToDecimal, buyerFields, buyerIssues, checkoutClassName, checkoutScreen, checkoutSteps, cleanBuyer, contactHref, countryOptions, deadlineAnnouncement, deadlineState, formatCountdown, formatFeeAmount, formatFiat, formatPeriod, formatTokenAmount, grantableOffer, groupMethodsByToken, handOverPayment, instructionsChainId, invoiceTotals, isConfirmationError, isFinalPaymentFailure, isInvoicePaymentOnTheWay, isInvoicePaymentUnresolved, isMovedMoneyFailure, isPaidElsewhere, isPayerProofError, isPaymentAccepted, isPaymentOnTheWay, isQuoteEnding, isSameWallet, isSlow, isSmartWallet, leftTheWalletText, lockPrice, lockedPriceOnWallet, methodErrorText, minorToDecimal, needsLeaveConfirm, needsPayerProof, needsTheClock, paidSteps, payInvoice, payPath, payerProofErrorText, qrPath, quoteAmounts, quoteRate, receivedAmount, refundRateMoved, refundTransfer, refusalText, restRateText, screensPayingWallets, sentBeforeDeadline, shouldHandOver, takeOverOpens, unconfirmedFollowUp, unconfirmedTxKey, underpaidRest, useAsyncValue, useAutoReturn, useCheckoutContext, useCheckoutEvents, useCheckoutState, useCheckoutStore, useConnectedWallet, useNovaPayments, useNow, useOptionalCheckoutContext, usePaidCallback, usePayerProof, usePayment, usePaymentFacts, usePaymentHandOver, usePaymentsConnection, usePaymentsLabels, useRefund, useRereadValue, useWalletConnection, walletErrorKind, walletOnConfirmStep };
2978
- export type { AutoPayTerms, BalanceShortfall, BuyerCollect, BuyerField, BuyerIssue, CheckoutContextValue, CheckoutHeaderProps, CheckoutNetworkOptionProps, CheckoutPartState, CheckoutPrimaryButtonProps, CheckoutQrCodeProps, CheckoutScreen, CheckoutScreenChoices, CheckoutScreenProps, CheckoutStatusIconProps, CheckoutStep, CheckoutStepperProps, CheckoutTokenGroup, CheckoutTokenOptionProps, ConfirmProblem, HandOverParams, LocaleSwitcherProps, LockPriceStore, NovaPaymentsLabelsContext, NovaPaymentsOwnConnection, NovaPaymentsProviderCustomization, NovaPaymentsProviderProps, NovaPaymentsSettings, OutcomeKind, PayInvoiceParams, PayPath, PayerProofFlow, PayerProofProblem, PayerProofStep, Payment, PaymentCheckoutChildCustomizations, PaymentCheckoutClassNames, PaymentCheckoutComponents, PaymentCheckoutConfig, PaymentCheckoutCustomization, PaymentCheckoutDisplay, PaymentCheckoutHandlers, PaymentCheckoutProps, PaymentStatus, PaymentWalletErrorKind, PaymentsConnectionMode, PaymentsPulsar, QuoteAmounts, RefundButtonProps, RefundDialogProps, RefundFlow, RefundInstructions, RefundProblem, RefundRequest, RefundStep, SentBeforeDeadlineParams, SentPayment, UnconfirmedFollowUp, UseAutoReturnParams, UseCheckoutEventsParams, UseCheckoutStoreOptions, UsePayerProofParams, UsePaymentHandOverParams, UsePaymentParams, UseRefundParams, WalletConnection, WalletPromptKind, WalletPromptProps };
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 };