@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.
- package/README.md +10 -5
- package/dist/chunk-7FQXTBOY.cjs +1 -0
- package/dist/chunk-7HSDAUKN.js +1 -0
- package/dist/chunk-EMYW4LI7.js +1 -0
- package/dist/chunk-HRTXVGBJ.cjs +1 -0
- package/dist/de-DXFDX3GR.js +1 -0
- package/dist/de-TJ6BGSUG.cjs +1 -0
- package/dist/es-DCARFZ3R.js +1 -0
- package/dist/es-I4V64VEP.cjs +1 -0
- package/dist/evm/index.cjs +1 -1
- package/dist/evm/index.d.cts +13 -5
- package/dist/evm/index.d.ts +13 -5
- package/dist/evm/index.js +1 -1
- package/dist/i18n/index.cjs +1 -1
- package/dist/i18n/index.d.cts +2 -2
- package/dist/i18n/index.d.ts +2 -2
- package/dist/i18n/index.js +1 -1
- package/dist/index.cjs +2 -2
- package/dist/index.css +198 -47
- package/dist/index.d.cts +174 -48
- package/dist/index.d.ts +174 -48
- package/dist/index.js +2 -2
- package/dist/it-N36S2FXH.js +1 -0
- package/dist/it-RQJGHQPP.cjs +1 -0
- package/dist/{locales-DzMinYsr.d.cts → locales-DP2jStIs.d.cts} +66 -5
- package/dist/{locales-DzMinYsr.d.ts → locales-DP2jStIs.d.ts} +66 -5
- package/dist/solana/index.cjs +1 -1
- package/dist/solana/index.js +1 -1
- package/dist/uk-FFP4RBO4.js +1 -0
- package/dist/uk-HYM26VN5.cjs +1 -0
- package/dist/zhCN-EKUFCQTZ.js +1 -0
- package/dist/zhCN-Q5DO4HXO.cjs +1 -0
- package/package.json +10 -11
- package/dist/chunk-PUMIYLSN.js +0 -1
- package/dist/chunk-S3L4QDPT.cjs +0 -1
- package/dist/chunk-WOAPFVQF.js +0 -1
- package/dist/chunk-XOVRZTAM.cjs +0 -1
- package/dist/de-53SSE6O2.js +0 -1
- package/dist/de-LB5XSRMX.cjs +0 -1
- package/dist/es-LP3HJ4KB.js +0 -1
- package/dist/es-VDW2RZMP.cjs +0 -1
- package/dist/it-6IQFXLAR.cjs +0 -1
- package/dist/it-JJ5Z5EUF.js +0 -1
- package/dist/uk-EI4N5BMM.js +0 -1
- package/dist/uk-FVCYLYSB.cjs +0 -1
- package/dist/zhCN-BZBMKUUA.js +0 -1
- 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)
|
|
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
|
|
138
|
-
*
|
|
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
|
|
408
|
-
*
|
|
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
|
|
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
|
-
*
|
|
1224
|
-
*
|
|
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.
|
|
1326
|
-
*
|
|
1327
|
-
*
|
|
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
|
|
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, `
|
|
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`).
|
|
1995
|
-
* checkout
|
|
1996
|
-
*
|
|
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,
|
|
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
|
|
2584
|
+
/** The checkout store: read when a payment is handed over, and followed for the payments Quasar finds. */
|
|
2484
2585
|
store: {
|
|
2485
|
-
getState: () =>
|
|
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
|
-
*
|
|
2505
|
-
*
|
|
2506
|
-
*
|
|
2507
|
-
*
|
|
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,
|
|
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.
|
|
2705
|
-
*
|
|
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,
|
|
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 };
|