@tuwaio/nova-payments 0.3.0 → 0.5.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 (43) hide show
  1. package/README.md +12 -1
  2. package/dist/chunk-BPBRT7WV.cjs +1 -0
  3. package/dist/chunk-SB5LW2OQ.js +1 -0
  4. package/dist/de-PVPQNE4K.js +1 -0
  5. package/dist/de-RZFQ3674.cjs +1 -0
  6. package/dist/es-GOJORJOI.js +1 -0
  7. package/dist/es-LRJYQNXS.cjs +1 -0
  8. package/dist/evm/index.cjs +1 -1
  9. package/dist/evm/index.js +1 -1
  10. package/dist/i18n/index.cjs +1 -1
  11. package/dist/i18n/index.d.cts +2 -2
  12. package/dist/i18n/index.d.ts +2 -2
  13. package/dist/i18n/index.js +1 -1
  14. package/dist/index.cjs +2 -2
  15. package/dist/index.css +3 -0
  16. package/dist/index.d.cts +117 -31
  17. package/dist/index.d.ts +117 -31
  18. package/dist/index.js +2 -2
  19. package/dist/it-AHKP5KMI.cjs +1 -0
  20. package/dist/it-AYCHUHO5.js +1 -0
  21. package/dist/{locales-dTcrLl9B.d.cts → locales-fU-NVESw.d.cts} +41 -28
  22. package/dist/{locales-dTcrLl9B.d.ts → locales-fU-NVESw.d.ts} +41 -28
  23. package/dist/solana/index.cjs +1 -1
  24. package/dist/solana/index.js +1 -1
  25. package/dist/{types-DOxwRLyU.d.ts → types-DQDwgCpt.d.cts} +17 -1
  26. package/dist/{types-DOxwRLyU.d.cts → types-DQDwgCpt.d.ts} +17 -1
  27. package/dist/uk-3MU32HNY.js +1 -0
  28. package/dist/uk-ITONA5SG.cjs +1 -0
  29. package/dist/zhCN-EOV4NMX5.js +1 -0
  30. package/dist/zhCN-W2PLK7SO.cjs +1 -0
  31. package/package.json +3 -3
  32. package/dist/chunk-4HBN6N7D.cjs +0 -1
  33. package/dist/chunk-A2WIFZQB.js +0 -1
  34. package/dist/de-5UOOKHHH.cjs +0 -1
  35. package/dist/de-U3SERR3Y.js +0 -1
  36. package/dist/es-J6MJIGEI.js +0 -1
  37. package/dist/es-WSJ36B6Y.cjs +0 -1
  38. package/dist/it-KX7WWME3.js +0 -1
  39. package/dist/it-QORQLELA.cjs +0 -1
  40. package/dist/uk-GMKBC44N.js +0 -1
  41. package/dist/uk-R2A3XIGT.cjs +0 -1
  42. package/dist/zhCN-5JP4MWXH.cjs +0 -1
  43. package/dist/zhCN-AX2E4I6A.js +0 -1
package/dist/index.css CHANGED
@@ -1149,6 +1149,9 @@
1149
1149
  .novapay-label-fade {
1150
1150
  animation: novapay-page-fade 120ms ease-out;
1151
1151
  }
1152
+ .novapay-payee-wait {
1153
+ animation: novapay-page-fade 200ms ease-out 300ms both;
1154
+ }
1152
1155
  .novapay-status-reveal {
1153
1156
  animation: novapay-status-reveal 300ms cubic-bezier(0.2, 0, 0, 1);
1154
1157
  }
package/dist/index.d.cts CHANGED
@@ -1,8 +1,8 @@
1
- import { P as PaymentsAdapter, a as PaymentFamily, C as CheckoutWallet, N as NativeFee } from './types-DOxwRLyU.cjs';
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-DOxwRLyU.cjs';
1
+ import { P as PaymentsAdapter, a as PaymentFamily, C as CheckoutWallet, N as NativeFee } from './types-DQDwgCpt.cjs';
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-DQDwgCpt.cjs';
3
3
  import * as react from 'react';
4
4
  import { ReactNode, ComponentType, ButtonHTMLAttributes, Context } from 'react';
5
- import { CheckoutMethod, CheckoutView, CheckoutPhase, CheckoutQuote, CheckoutError, CheckoutState, PaymentInstructions, CheckoutApi, EventSourceConstructor, CheckoutStore, RefundPhase, RefundState, RefundStore, PayerProofMessage, CheckoutMerchant } from '@tuwaio/quasar-sdk/checkout';
5
+ import { CheckoutMethod, CheckoutView, CheckoutPhase, CheckoutQuote, CheckoutError, CheckoutState, PaymentInstructions, CheckoutApi, EventSourceConstructor, CheckoutStore, PayeeRefusal, PayeeCheck, PayeeVerifier, RefundPhase, RefundState, RefundStore, PayeeOptions, PayerProofMessage, CheckoutMerchant } from '@tuwaio/quasar-sdk/checkout';
6
6
  import { NovaPaymentsLabels, CheckoutLocale, NovaPaymentsLabelOverrides } from './i18n/index.cjs';
7
7
  import { Transaction } from '@tuwaio/pulsar-core';
8
8
  import { StatusTone, StatusEdgeProps } from '@tuwaio/nova-core';
@@ -33,7 +33,7 @@ declare function BuyerScreen(): react.JSX.Element | null;
33
33
  * confirm (`unconfirmed`: it may still arrive, so the buyer checks the wallet before paying again), a payment that
34
34
  * failed for good while the invoice still takes one (`failed`: the buyer may pay again) or its outcome.
35
35
  */
36
- type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'confirmWallet' | 'pay' | 'qr' | 'confirm' | 'unconfirmed' | 'failed' | 'paid' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked';
36
+ type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'confirmWallet' | 'pay' | 'qr' | 'confirm' | 'unconfirmed' | 'failed' | 'paid' | 'underpaid' | 'needs_review' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked';
37
37
  /** Choices of the buyer that the checkout store does not hold. */
38
38
  interface CheckoutScreenChoices {
39
39
  /** Pay from a wallet in this browser (default) or scan a QR code with a phone. */
@@ -144,8 +144,8 @@ declare function groupMethodsByToken(methods: CheckoutMethod[], walletChainId?:
144
144
  * the wallet signs, the payment is handed to Quasar and it confirms, and on a payer the wallet check refused
145
145
  * (`blocked`, where the buyer can pay with another wallet); it ends with the paid outcome and with the outcomes in which
146
146
  * a deadline means nothing. A payment sent before the deadline counts: Quasar keeps an `open` or `underpaid` invoice
147
- * while a payment it learned of before the deadline confirms (for a limited time), and holds a payment that lands after
148
- * the invoice closed for the seller to accept or return.
147
+ * while a payment it learned of before the deadline confirms (for a limited time), and records a payment that lands
148
+ * after the invoice closed for the seller to accept or return.
149
149
  *
150
150
  * @param status - The invoice state (`checkout.invoice.status`).
151
151
  * @param screen - The screen shown.
@@ -154,9 +154,8 @@ declare function groupMethodsByToken(methods: CheckoutMethod[], walletChainId?:
154
154
  * `confirming` while the payment is on its way (the countdown shows; at zero the confirm step says that the payment
155
155
  * sent in time is being confirmed) and while Quasar could not confirm it (`unconfirmed`: the buyer checks the wallet
156
156
  * before paying again, so no minutes left to pay are announced), or `null` once the payment succeeded (`paid`), on the
157
- * outcomes in
158
- * which a deadline means nothing (`held`, `refunded`, `expired`, `cancelled`, `replaced`) and for an invoice that can
159
- * no longer be paid. `closed` while part of an underpaid invoice arrived and its rest cannot be paid: the countdown still
157
+ * outcomes in which a deadline means nothing (`needs_review`, `refunded`, `expired`, `cancelled`, `replaced`) and for an
158
+ * invoice that can no longer be paid. `closed` while part of an underpaid invoice arrived and its rest cannot be paid: the countdown still
160
159
  * shows, as the time after which the seller can refund, and no minutes left to pay are announced.
161
160
  */
162
161
  declare function deadlineState(status: string, screen: CheckoutScreen, restPayable?: boolean): 'paying' | 'confirming' | 'closed' | null;
@@ -190,7 +189,7 @@ declare function lockedPriceOnWallet(params: {
190
189
  }): 'keep' | 'lock' | 'release';
191
190
  /**
192
191
  * What the active wallet changing does on the step that confirms the wallet, where no new price is locked yet: the step
193
- * asks the wallet connected to sign, never the one the store last held.
192
+ * asks the wallet connected to sign, never the one the store last had.
194
193
  *
195
194
  * @param params - What the change happens over.
196
195
  * @param params.open - The step shows.
@@ -506,7 +505,7 @@ interface CheckoutStepperProps {
506
505
  declare function CheckoutStepper({ steps, labels, className, stepClassName }: CheckoutStepperProps): react.JSX.Element;
507
506
 
508
507
  /** The outcomes this screen shows. */
509
- type OutcomeKind = Extract<CheckoutScreen, 'unconfirmed' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked'>;
508
+ type OutcomeKind = Extract<CheckoutScreen, 'unconfirmed' | 'underpaid' | 'needs_review' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked'>;
510
509
  /** "Contact <seller>": the seller's support email about the invoice, its site, or the app's handler. @internal */
511
510
  declare function ContactLink(): react.JSX.Element | null;
512
511
  /**
@@ -828,7 +827,11 @@ interface PaymentCheckoutComponents {
828
827
  StatusIcon?: ComponentType<CheckoutStatusIconProps>;
829
828
  /** The strip and the wash of the status color along the top of the checkout (`StatusEdge` of `@tuwaio/nova-core`). */
830
829
  StatusEdge?: ComponentType<StatusEdgeProps>;
831
- /** Whole screens, by the screen they replace (for example `paid` or `loading`). */
830
+ /**
831
+ * Whole screens, by the screen they replace (for example `paid` or `loading`). A replacement of `pay` or `qr` shows
832
+ * nothing of the price (its address, its QR code) until `payeeStatus` of the checkout state is `verified`, as
833
+ * {@link PayeeScreen} does in its place; the checkout sends no payment before that anyway (`payInvoice`).
834
+ */
832
835
  screens?: Partial<Record<CheckoutScreen, ComponentType<CheckoutScreenProps>>>;
833
836
  }
834
837
  /**
@@ -926,9 +929,9 @@ interface PaymentCheckoutHandlers {
926
929
  /**
927
930
  * The locked price ran out (`quote`), or the invoice expired (`invoice`). Either can happen while a payment is on its
928
931
  * way: the invoice can still close while it confirms (Quasar waits for a payment it learned of
929
- * before the deadline only for a limited time, and holds a payment that lands later for the seller to accept or
932
+ * before the deadline only for a limited time, and records a payment that lands later for the seller to accept or
930
933
  * return), so do not offer a new invoice at once when `paymentOnTheWay` is `true`; the checkout keeps following the
931
- * invoice and shows a paid or held outcome if it changes.
934
+ * invoice and shows a paid or review outcome if it changes.
932
935
  *
933
936
  * @param params - What expired.
934
937
  * @param params.kind - `quote` or `invoice`.
@@ -1038,6 +1041,14 @@ interface PaymentCheckoutProps {
1038
1041
  * leaving it out offers the QR code for Solana methods only.
1039
1042
  */
1040
1043
  payUrl?: string | null;
1044
+ /**
1045
+ * The merchant's own receiving addresses, from the merchant's integration rather than from Quasar (the `#payout=`
1046
+ * part of a `payUrl` the server SDK made with `payoutAddresses`): the checkout refuses to show or pay a quote whose
1047
+ * address is not among them, whatever Quasar's database says. Without them the checkout still requires the address's
1048
+ * own signature of its payout record, which a swap in Quasar's database could carry for its own wallet. EVM addresses
1049
+ * in any letter case. A change makes the checkout read the invoice again.
1050
+ */
1051
+ payoutAddresses?: readonly string[];
1041
1052
  /**
1042
1053
  * Connects a wallet of a chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1043
1054
  * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection of `NovaPaymentsProvider`)
@@ -1123,7 +1134,7 @@ declare function CheckoutFrame({ className, withDetails, leave, }: {
1123
1134
  * }
1124
1135
  * ```
1125
1136
  */
1126
- 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;
1137
+ declare function PaymentCheckout({ token, display, open, onOpenChange, onClose, baseUrl, api, EventSource, pollMs, payUrl, payoutAddresses, onConnectWallet, onPaid, autoReturnSeconds, onContact, locale: pageLanguage, className, customization, }: PaymentCheckoutProps): react.JSX.Element;
1127
1138
  /**
1128
1139
  * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1129
1140
  * no step can move its top.
@@ -1447,6 +1458,74 @@ declare function MethodScreen(): react.JSX.Element | null;
1447
1458
  */
1448
1459
  declare function PaidScreen(): react.JSX.Element | null;
1449
1460
 
1461
+ /**
1462
+ * @file The payee of the quote the checkout shows: where the store's check of it stands, and the check of its payout
1463
+ * record's signature by the chain adapters. The checkout shows a quote's address and asks the wallet to pay only once
1464
+ * the store verified this very quote (`payee` of `createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`).
1465
+ */
1466
+
1467
+ /**
1468
+ * Where the check of the shown quote's payee stands: `checking` until the store checked this very quote (also while
1469
+ * it still holds the check of an earlier quote), then `verified` or `refused`.
1470
+ */
1471
+ type PayeeStatus = {
1472
+ status: 'checking';
1473
+ } | {
1474
+ status: 'verified';
1475
+ } | {
1476
+ status: 'refused';
1477
+ reason: PayeeRefusal;
1478
+ };
1479
+ /**
1480
+ * Where the check of the quote's payee stands, from the checkout store's state.
1481
+ *
1482
+ * @param state - `quote` and `payeeCheck` of the checkout store.
1483
+ * @returns The status for this very quote: a check of another quote counts as `checking`.
1484
+ */
1485
+ declare function payeeStatus(state: {
1486
+ quote?: CheckoutQuote | null;
1487
+ payeeCheck?: PayeeCheck | null;
1488
+ }): PayeeStatus;
1489
+ /**
1490
+ * Whether the store verified the payee of this very quote: the only state in which the checkout sends a payment.
1491
+ *
1492
+ * @param state - `quote` and `payeeCheck` of the checkout store.
1493
+ * @param quote - The quote about to be paid.
1494
+ * @returns `true` once the store's check of this quote found its payee verified.
1495
+ */
1496
+ declare function payeeVerified(state: {
1497
+ payeeCheck?: PayeeCheck | null;
1498
+ }, quote: CheckoutQuote): boolean;
1499
+ /**
1500
+ * Checks the signature of a quote's payout record with the adapter of its chain family (`verifyPayoutRecord`): the
1501
+ * {@link PayeeVerifier} of a checkout over its adapters.
1502
+ *
1503
+ * Side effects: on EVM, a smart wallet's signature is put to its contract through the app's RPC.
1504
+ *
1505
+ * @param adapters - The checkout's payment adapters.
1506
+ * @param params - The record, its signature and the network (CAIP-2) of the quote.
1507
+ * @returns Whether the signature holds, or `null` when no adapter of the family checks signatures.
1508
+ */
1509
+ declare function verifyPayeeWith(adapters: readonly PaymentsAdapter[] | undefined, params: Parameters<PayeeVerifier>[0]): Promise<boolean | null>;
1510
+
1511
+ /**
1512
+ * What the pay and QR steps show instead of the payment until the checkout store verified the payee of the quote. While
1513
+ * the check runs, a wait that appears only when it takes more than a moment: an ordinary wallet's signature is checked
1514
+ * in the page at once, a smart wallet's asks its contract on the network. When the address could not be confirmed as
1515
+ * the merchant's, a refusal: the address is never shown and the wallet never asked, whatever the reason, which
1516
+ * `data-payee-refusal` names for the integrator (`payee_unsigned`, `payee_mismatch`, `payee_not_pinned`,
1517
+ * `payee_unverified`).
1518
+ *
1519
+ * @param props - Where the check stands.
1520
+ * @param props.payee - `checking`, or `refused` with its reason ({@link payeeStatus}).
1521
+ * @returns The step.
1522
+ */
1523
+ declare function PayeeScreen({ payee }: {
1524
+ payee: Exclude<PayeeStatus, {
1525
+ status: 'verified';
1526
+ }>;
1527
+ }): react.JSX.Element;
1528
+
1450
1529
  /**
1451
1530
  * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
1452
1531
  * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
@@ -1524,7 +1603,7 @@ interface RefundFlow {
1524
1603
  /** The refund store's phase. */
1525
1604
  phase: RefundPhase;
1526
1605
  /**
1527
- * What a refund would send, before it is asked for: a requested refund holds its amount until it is sent.
1606
+ * What a refund would send, before it is asked for: a requested refund keeps its amount until it is sent.
1528
1607
  *
1529
1608
  * @param request - What to refund.
1530
1609
  * @returns The preview; `null` when the store cannot show one; `refused` when Quasar would refuse it (`error` says why).
@@ -1883,10 +1962,16 @@ interface UseCheckoutStoreOptions {
1883
1962
  pollMs?: number;
1884
1963
  /** Whether to load and follow the invoice; `false` keeps the idle store, which makes no requests. Defaults to `true`. */
1885
1964
  enabled?: boolean;
1965
+ /**
1966
+ * How the store checks the payee of each quote (`payee` of `createCheckoutStore`): the signature verifier, read when
1967
+ * the store is created, and the merchant's pinned addresses, whose change makes the store again, so that no quote is
1968
+ * checked against pins the page has since replaced.
1969
+ */
1970
+ payee?: PayeeOptions;
1886
1971
  }
1887
1972
  /**
1888
1973
  * The checkout store of an invoice (`createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`): created and loaded
1889
- * after mount, destroyed on unmount or when `token` or `baseUrl` change. Until then it is a store in the `loading`
1974
+ * after mount, destroyed on unmount or when `token`, `baseUrl` or the pinned payout addresses change. Until then it is a store in the `loading`
1890
1975
  * phase that makes no requests.
1891
1976
  *
1892
1977
  * Side effects: the store reads the checkout and follows the invoice (an `EventSource` on its `events` route, or a
@@ -2366,9 +2451,9 @@ declare function instructionsChainId(instructions: PaymentInstructions): string;
2366
2451
  interface PayInvoiceParams {
2367
2452
  /** The adapter of the quote's chain family. */
2368
2453
  adapter: PaymentsAdapter;
2369
- /** The checkout store (only `submit`, `relay` and `relayFromPage` are used). */
2454
+ /** The checkout store (only `submit`, `relay`, `relayFromPage` and `payeeCheck` are used). */
2370
2455
  store: {
2371
- getState: () => Pick<CheckoutState, 'submit' | 'relay'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2456
+ getState: () => Pick<CheckoutState, 'submit' | 'relay' | 'payeeCheck'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2372
2457
  };
2373
2458
  /** The locked quote. */
2374
2459
  quote: CheckoutQuote;
@@ -2408,8 +2493,8 @@ interface PayInvoiceParams {
2408
2493
  *
2409
2494
  * @param params - See {@link PayInvoiceParams}.
2410
2495
  * @returns Whether Quasar took the payment (the store's `error` says why not).
2411
- * @throws {@link PaymentWalletError} `unsupported` when the adapter or the quote cannot take the path; the wallet's
2412
- * error when it refuses or fails.
2496
+ * @throws {@link PaymentWalletError} `unsupported` when the store has not verified the payee of this quote
2497
+ * (`payeeCheck`), or the adapter or the quote cannot take the path; the wallet's error when it refuses or fails.
2413
2498
  */
2414
2499
  declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onBatchAccepted, onSent, }: PayInvoiceParams): Promise<boolean>;
2415
2500
 
@@ -2768,11 +2853,12 @@ declare function failedPaymentTx(error: CheckoutError | null | undefined): strin
2768
2853
  /**
2769
2854
  * What the checkout says about a payment that left the wallet, or may have, from the store's error: a transaction that
2770
2855
  * does not pay the invoice (`pay.mismatch`; `pay.mismatchTakenElsewhere` when Quasar credited it to another invoice;
2771
- * `pay.mismatchHeldElsewhere` when another invoice holds it for a refund only, `held`;
2772
- * `pay.mismatchOtherWallet` for a transfer from a wallet that did not confirm the invoice, `pay.mismatchOtherWalletHeld`
2773
- * when Quasar recorded it as a held transfer the seller returns, `held`; `pay.mismatchNoReferenceHeld` for a Solana Pay
2774
- * transfer without the invoice's reference held on this invoice, `held`; `pay.mismatchChargeHeld` for a payment sent
2775
- * under an earlier price of the invoice, `quote_changed`), a payment Quasar closed after 24 hours without a result on chain
2856
+ * `pay.mismatchUnmatchedElsewhere` when it is an unmatched transfer at another invoice, refunded only, `unmatched`;
2857
+ * `pay.mismatchOtherWallet` for a transfer from a wallet that did not confirm the invoice,
2858
+ * `pay.mismatchOtherWalletUnmatched` when Quasar recorded it as an unmatched transfer the seller returns, `unmatched`;
2859
+ * `pay.mismatchNoReferenceUnmatched` for a Solana Pay transfer without the invoice's reference recorded on this
2860
+ * invoice, `unmatched`; `pay.mismatchChargeUnmatched` for a payment sent under an earlier price of the invoice,
2861
+ * `quote_changed`), a payment Quasar closed after 24 hours without a result on chain
2776
2862
  * (`outcome.unconfirmedClosed`), a transaction another invoice handed over first (`outcome.unconfirmedTakenElsewhere`)
2777
2863
  * and a payment the network confirmed that Quasar has not recorded yet (`outcome.unconfirmedSettlementRetrying` while
2778
2864
  * Quasar settles it again daily, for 30 days, else `outcome.unconfirmedSettlementFailed`). Never "it failed", "only the
@@ -2925,9 +3011,9 @@ declare function lockPrice(store: LockPriceStore, showConfirmWallet: (show: bool
2925
3011
  */
2926
3012
  declare function isPayerProofError(error: CheckoutError | null | undefined): boolean;
2927
3013
  /**
2928
- * Whether an error belongs on the step that confirms the wallet. The store's error may be about something else: a
2929
- * transfer held from another wallet, or a price refused to the last wallet, opened the step with "Something went wrong"
2930
- * before the wallet was asked anything.
3014
+ * Whether an error belongs on the step that confirms the wallet. The store's error may be about something else: an
3015
+ * unmatched transfer from another wallet, or a price refused to the last wallet, opened the step with "Something went
3016
+ * wrong" before the wallet was asked anything.
2931
3017
  *
2932
3018
  * @param error - The checkout store's error, if any.
2933
3019
  * @returns `true` for a refusal of the confirmation or a failure of its requests.
@@ -2998,5 +3084,5 @@ declare function invoiceTotals(invoice: CheckoutView['invoice']): {
2998
3084
  total: string;
2999
3085
  };
3000
3086
 
3001
- export { AmountStep, 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, balanceShortfall, baseUnitsToDecimal, buyerFields, buyerIssues, checkoutClassName, checkoutScreen, checkoutSteps, cleanBuyer, contactHref, countryOptions, deadlineAnnouncement, deadlineState, failedPaymentTx, formatCountdown, formatFeeAmount, formatFiat, formatTokenAmount, 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, 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 };
3002
- export type { 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 };
3087
+ export { AmountStep, 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, PayeeScreen, PaymentCheckout, PaymentFamily, PaymentWalletError, PaymentsAdapter, QUOTE_WARNING_MS, QrScreen, RefundButton, RefundDialog, RefundSteps, ScreenBody, SellerDetailsContent, SummaryFooter, WalletPrompt, addressOfWallet, balanceShortfall, baseUnitsToDecimal, buyerFields, buyerIssues, checkoutClassName, checkoutScreen, checkoutSteps, cleanBuyer, contactHref, countryOptions, deadlineAnnouncement, deadlineState, failedPaymentTx, formatCountdown, formatFeeAmount, formatFiat, formatTokenAmount, 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, payeeStatus, payeeVerified, payerProofErrorText, paymentFailedText, qrPath, quoteAmounts, quoteRate, receivedAmount, refundRateMoved, refundTransfer, refusalText, restRateText, screensPayingWallets, sentBeforeDeadline, shownLocale, unconfirmedFollowUp, unconfirmedTxKey, underpaidRest, useAsyncValue, useAutoReturn, useCheckoutContext, useCheckoutEvents, useCheckoutState, useCheckoutStore, useConnectedWallet, useNovaPayments, useNow, useOptionalCheckoutContext, usePaidCallback, usePayerProof, usePayment, usePaymentFacts, usePaymentHandOver, usePaymentsConnection, usePaymentsLabels, useRefund, useRereadValue, useWalletConnection, verifyPayeeWith, walletErrorKind, walletOnConfirmStep };
3088
+ export type { 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, PayeeStatus, 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 };
package/dist/index.d.ts CHANGED
@@ -1,8 +1,8 @@
1
- import { P as PaymentsAdapter, a as PaymentFamily, C as CheckoutWallet, N as NativeFee } from './types-DOxwRLyU.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-DOxwRLyU.js';
1
+ import { P as PaymentsAdapter, a as PaymentFamily, C as CheckoutWallet, N as NativeFee } from './types-DQDwgCpt.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-DQDwgCpt.js';
3
3
  import * as react from 'react';
4
4
  import { ReactNode, ComponentType, ButtonHTMLAttributes, Context } from 'react';
5
- import { CheckoutMethod, CheckoutView, CheckoutPhase, CheckoutQuote, CheckoutError, CheckoutState, PaymentInstructions, CheckoutApi, EventSourceConstructor, CheckoutStore, RefundPhase, RefundState, RefundStore, PayerProofMessage, CheckoutMerchant } from '@tuwaio/quasar-sdk/checkout';
5
+ import { CheckoutMethod, CheckoutView, CheckoutPhase, CheckoutQuote, CheckoutError, CheckoutState, PaymentInstructions, CheckoutApi, EventSourceConstructor, CheckoutStore, PayeeRefusal, PayeeCheck, PayeeVerifier, RefundPhase, RefundState, RefundStore, PayeeOptions, PayerProofMessage, CheckoutMerchant } from '@tuwaio/quasar-sdk/checkout';
6
6
  import { NovaPaymentsLabels, CheckoutLocale, NovaPaymentsLabelOverrides } from './i18n/index.js';
7
7
  import { Transaction } from '@tuwaio/pulsar-core';
8
8
  import { StatusTone, StatusEdgeProps } from '@tuwaio/nova-core';
@@ -33,7 +33,7 @@ declare function BuyerScreen(): react.JSX.Element | null;
33
33
  * confirm (`unconfirmed`: it may still arrive, so the buyer checks the wallet before paying again), a payment that
34
34
  * failed for good while the invoice still takes one (`failed`: the buyer may pay again) or its outcome.
35
35
  */
36
- type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'confirmWallet' | 'pay' | 'qr' | 'confirm' | 'unconfirmed' | 'failed' | 'paid' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked';
36
+ type CheckoutScreen = 'loading' | 'error' | 'buyer' | 'method' | 'confirmWallet' | 'pay' | 'qr' | 'confirm' | 'unconfirmed' | 'failed' | 'paid' | 'underpaid' | 'needs_review' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked';
37
37
  /** Choices of the buyer that the checkout store does not hold. */
38
38
  interface CheckoutScreenChoices {
39
39
  /** Pay from a wallet in this browser (default) or scan a QR code with a phone. */
@@ -144,8 +144,8 @@ declare function groupMethodsByToken(methods: CheckoutMethod[], walletChainId?:
144
144
  * the wallet signs, the payment is handed to Quasar and it confirms, and on a payer the wallet check refused
145
145
  * (`blocked`, where the buyer can pay with another wallet); it ends with the paid outcome and with the outcomes in which
146
146
  * a deadline means nothing. A payment sent before the deadline counts: Quasar keeps an `open` or `underpaid` invoice
147
- * while a payment it learned of before the deadline confirms (for a limited time), and holds a payment that lands after
148
- * the invoice closed for the seller to accept or return.
147
+ * while a payment it learned of before the deadline confirms (for a limited time), and records a payment that lands
148
+ * after the invoice closed for the seller to accept or return.
149
149
  *
150
150
  * @param status - The invoice state (`checkout.invoice.status`).
151
151
  * @param screen - The screen shown.
@@ -154,9 +154,8 @@ declare function groupMethodsByToken(methods: CheckoutMethod[], walletChainId?:
154
154
  * `confirming` while the payment is on its way (the countdown shows; at zero the confirm step says that the payment
155
155
  * sent in time is being confirmed) and while Quasar could not confirm it (`unconfirmed`: the buyer checks the wallet
156
156
  * before paying again, so no minutes left to pay are announced), or `null` once the payment succeeded (`paid`), on the
157
- * outcomes in
158
- * which a deadline means nothing (`held`, `refunded`, `expired`, `cancelled`, `replaced`) and for an invoice that can
159
- * no longer be paid. `closed` while part of an underpaid invoice arrived and its rest cannot be paid: the countdown still
157
+ * outcomes in which a deadline means nothing (`needs_review`, `refunded`, `expired`, `cancelled`, `replaced`) and for an
158
+ * invoice that can no longer be paid. `closed` while part of an underpaid invoice arrived and its rest cannot be paid: the countdown still
160
159
  * shows, as the time after which the seller can refund, and no minutes left to pay are announced.
161
160
  */
162
161
  declare function deadlineState(status: string, screen: CheckoutScreen, restPayable?: boolean): 'paying' | 'confirming' | 'closed' | null;
@@ -190,7 +189,7 @@ declare function lockedPriceOnWallet(params: {
190
189
  }): 'keep' | 'lock' | 'release';
191
190
  /**
192
191
  * What the active wallet changing does on the step that confirms the wallet, where no new price is locked yet: the step
193
- * asks the wallet connected to sign, never the one the store last held.
192
+ * asks the wallet connected to sign, never the one the store last had.
194
193
  *
195
194
  * @param params - What the change happens over.
196
195
  * @param params.open - The step shows.
@@ -506,7 +505,7 @@ interface CheckoutStepperProps {
506
505
  declare function CheckoutStepper({ steps, labels, className, stepClassName }: CheckoutStepperProps): react.JSX.Element;
507
506
 
508
507
  /** The outcomes this screen shows. */
509
- type OutcomeKind = Extract<CheckoutScreen, 'unconfirmed' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked'>;
508
+ type OutcomeKind = Extract<CheckoutScreen, 'unconfirmed' | 'underpaid' | 'needs_review' | 'refunded' | 'expired' | 'cancelled' | 'replaced' | 'blocked'>;
510
509
  /** "Contact <seller>": the seller's support email about the invoice, its site, or the app's handler. @internal */
511
510
  declare function ContactLink(): react.JSX.Element | null;
512
511
  /**
@@ -828,7 +827,11 @@ interface PaymentCheckoutComponents {
828
827
  StatusIcon?: ComponentType<CheckoutStatusIconProps>;
829
828
  /** The strip and the wash of the status color along the top of the checkout (`StatusEdge` of `@tuwaio/nova-core`). */
830
829
  StatusEdge?: ComponentType<StatusEdgeProps>;
831
- /** Whole screens, by the screen they replace (for example `paid` or `loading`). */
830
+ /**
831
+ * Whole screens, by the screen they replace (for example `paid` or `loading`). A replacement of `pay` or `qr` shows
832
+ * nothing of the price (its address, its QR code) until `payeeStatus` of the checkout state is `verified`, as
833
+ * {@link PayeeScreen} does in its place; the checkout sends no payment before that anyway (`payInvoice`).
834
+ */
832
835
  screens?: Partial<Record<CheckoutScreen, ComponentType<CheckoutScreenProps>>>;
833
836
  }
834
837
  /**
@@ -926,9 +929,9 @@ interface PaymentCheckoutHandlers {
926
929
  /**
927
930
  * The locked price ran out (`quote`), or the invoice expired (`invoice`). Either can happen while a payment is on its
928
931
  * way: the invoice can still close while it confirms (Quasar waits for a payment it learned of
929
- * before the deadline only for a limited time, and holds a payment that lands later for the seller to accept or
932
+ * before the deadline only for a limited time, and records a payment that lands later for the seller to accept or
930
933
  * return), so do not offer a new invoice at once when `paymentOnTheWay` is `true`; the checkout keeps following the
931
- * invoice and shows a paid or held outcome if it changes.
934
+ * invoice and shows a paid or review outcome if it changes.
932
935
  *
933
936
  * @param params - What expired.
934
937
  * @param params.kind - `quote` or `invoice`.
@@ -1038,6 +1041,14 @@ interface PaymentCheckoutProps {
1038
1041
  * leaving it out offers the QR code for Solana methods only.
1039
1042
  */
1040
1043
  payUrl?: string | null;
1044
+ /**
1045
+ * The merchant's own receiving addresses, from the merchant's integration rather than from Quasar (the `#payout=`
1046
+ * part of a `payUrl` the server SDK made with `payoutAddresses`): the checkout refuses to show or pay a quote whose
1047
+ * address is not among them, whatever Quasar's database says. Without them the checkout still requires the address's
1048
+ * own signature of its payout record, which a swap in Quasar's database could carry for its own wallet. EVM addresses
1049
+ * in any letter case. A change makes the checkout read the invoice again.
1050
+ */
1051
+ payoutAddresses?: readonly string[];
1041
1052
  /**
1042
1053
  * Connects a wallet of a chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1043
1054
  * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection of `NovaPaymentsProvider`)
@@ -1123,7 +1134,7 @@ declare function CheckoutFrame({ className, withDetails, leave, }: {
1123
1134
  * }
1124
1135
  * ```
1125
1136
  */
1126
- 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;
1137
+ declare function PaymentCheckout({ token, display, open, onOpenChange, onClose, baseUrl, api, EventSource, pollMs, payUrl, payoutAddresses, onConnectWallet, onPaid, autoReturnSeconds, onContact, locale: pageLanguage, className, customization, }: PaymentCheckoutProps): react.JSX.Element;
1127
1138
  /**
1128
1139
  * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1129
1140
  * no step can move its top.
@@ -1447,6 +1458,74 @@ declare function MethodScreen(): react.JSX.Element | null;
1447
1458
  */
1448
1459
  declare function PaidScreen(): react.JSX.Element | null;
1449
1460
 
1461
+ /**
1462
+ * @file The payee of the quote the checkout shows: where the store's check of it stands, and the check of its payout
1463
+ * record's signature by the chain adapters. The checkout shows a quote's address and asks the wallet to pay only once
1464
+ * the store verified this very quote (`payee` of `createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`).
1465
+ */
1466
+
1467
+ /**
1468
+ * Where the check of the shown quote's payee stands: `checking` until the store checked this very quote (also while
1469
+ * it still holds the check of an earlier quote), then `verified` or `refused`.
1470
+ */
1471
+ type PayeeStatus = {
1472
+ status: 'checking';
1473
+ } | {
1474
+ status: 'verified';
1475
+ } | {
1476
+ status: 'refused';
1477
+ reason: PayeeRefusal;
1478
+ };
1479
+ /**
1480
+ * Where the check of the quote's payee stands, from the checkout store's state.
1481
+ *
1482
+ * @param state - `quote` and `payeeCheck` of the checkout store.
1483
+ * @returns The status for this very quote: a check of another quote counts as `checking`.
1484
+ */
1485
+ declare function payeeStatus(state: {
1486
+ quote?: CheckoutQuote | null;
1487
+ payeeCheck?: PayeeCheck | null;
1488
+ }): PayeeStatus;
1489
+ /**
1490
+ * Whether the store verified the payee of this very quote: the only state in which the checkout sends a payment.
1491
+ *
1492
+ * @param state - `quote` and `payeeCheck` of the checkout store.
1493
+ * @param quote - The quote about to be paid.
1494
+ * @returns `true` once the store's check of this quote found its payee verified.
1495
+ */
1496
+ declare function payeeVerified(state: {
1497
+ payeeCheck?: PayeeCheck | null;
1498
+ }, quote: CheckoutQuote): boolean;
1499
+ /**
1500
+ * Checks the signature of a quote's payout record with the adapter of its chain family (`verifyPayoutRecord`): the
1501
+ * {@link PayeeVerifier} of a checkout over its adapters.
1502
+ *
1503
+ * Side effects: on EVM, a smart wallet's signature is put to its contract through the app's RPC.
1504
+ *
1505
+ * @param adapters - The checkout's payment adapters.
1506
+ * @param params - The record, its signature and the network (CAIP-2) of the quote.
1507
+ * @returns Whether the signature holds, or `null` when no adapter of the family checks signatures.
1508
+ */
1509
+ declare function verifyPayeeWith(adapters: readonly PaymentsAdapter[] | undefined, params: Parameters<PayeeVerifier>[0]): Promise<boolean | null>;
1510
+
1511
+ /**
1512
+ * What the pay and QR steps show instead of the payment until the checkout store verified the payee of the quote. While
1513
+ * the check runs, a wait that appears only when it takes more than a moment: an ordinary wallet's signature is checked
1514
+ * in the page at once, a smart wallet's asks its contract on the network. When the address could not be confirmed as
1515
+ * the merchant's, a refusal: the address is never shown and the wallet never asked, whatever the reason, which
1516
+ * `data-payee-refusal` names for the integrator (`payee_unsigned`, `payee_mismatch`, `payee_not_pinned`,
1517
+ * `payee_unverified`).
1518
+ *
1519
+ * @param props - Where the check stands.
1520
+ * @param props.payee - `checking`, or `refused` with its reason ({@link payeeStatus}).
1521
+ * @returns The step.
1522
+ */
1523
+ declare function PayeeScreen({ payee }: {
1524
+ payee: Exclude<PayeeStatus, {
1525
+ status: 'verified';
1526
+ }>;
1527
+ }): react.JSX.Element;
1528
+
1450
1529
  /**
1451
1530
  * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
1452
1531
  * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
@@ -1524,7 +1603,7 @@ interface RefundFlow {
1524
1603
  /** The refund store's phase. */
1525
1604
  phase: RefundPhase;
1526
1605
  /**
1527
- * What a refund would send, before it is asked for: a requested refund holds its amount until it is sent.
1606
+ * What a refund would send, before it is asked for: a requested refund keeps its amount until it is sent.
1528
1607
  *
1529
1608
  * @param request - What to refund.
1530
1609
  * @returns The preview; `null` when the store cannot show one; `refused` when Quasar would refuse it (`error` says why).
@@ -1883,10 +1962,16 @@ interface UseCheckoutStoreOptions {
1883
1962
  pollMs?: number;
1884
1963
  /** Whether to load and follow the invoice; `false` keeps the idle store, which makes no requests. Defaults to `true`. */
1885
1964
  enabled?: boolean;
1965
+ /**
1966
+ * How the store checks the payee of each quote (`payee` of `createCheckoutStore`): the signature verifier, read when
1967
+ * the store is created, and the merchant's pinned addresses, whose change makes the store again, so that no quote is
1968
+ * checked against pins the page has since replaced.
1969
+ */
1970
+ payee?: PayeeOptions;
1886
1971
  }
1887
1972
  /**
1888
1973
  * The checkout store of an invoice (`createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`): created and loaded
1889
- * after mount, destroyed on unmount or when `token` or `baseUrl` change. Until then it is a store in the `loading`
1974
+ * after mount, destroyed on unmount or when `token`, `baseUrl` or the pinned payout addresses change. Until then it is a store in the `loading`
1890
1975
  * phase that makes no requests.
1891
1976
  *
1892
1977
  * Side effects: the store reads the checkout and follows the invoice (an `EventSource` on its `events` route, or a
@@ -2366,9 +2451,9 @@ declare function instructionsChainId(instructions: PaymentInstructions): string;
2366
2451
  interface PayInvoiceParams {
2367
2452
  /** The adapter of the quote's chain family. */
2368
2453
  adapter: PaymentsAdapter;
2369
- /** The checkout store (only `submit`, `relay` and `relayFromPage` are used). */
2454
+ /** The checkout store (only `submit`, `relay`, `relayFromPage` and `payeeCheck` are used). */
2370
2455
  store: {
2371
- getState: () => Pick<CheckoutState, 'submit' | 'relay'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2456
+ getState: () => Pick<CheckoutState, 'submit' | 'relay' | 'payeeCheck'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2372
2457
  };
2373
2458
  /** The locked quote. */
2374
2459
  quote: CheckoutQuote;
@@ -2408,8 +2493,8 @@ interface PayInvoiceParams {
2408
2493
  *
2409
2494
  * @param params - See {@link PayInvoiceParams}.
2410
2495
  * @returns Whether Quasar took the payment (the store's `error` says why not).
2411
- * @throws {@link PaymentWalletError} `unsupported` when the adapter or the quote cannot take the path; the wallet's
2412
- * error when it refuses or fails.
2496
+ * @throws {@link PaymentWalletError} `unsupported` when the store has not verified the payee of this quote
2497
+ * (`payeeCheck`), or the adapter or the quote cannot take the path; the wallet's error when it refuses or fails.
2413
2498
  */
2414
2499
  declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onBatchAccepted, onSent, }: PayInvoiceParams): Promise<boolean>;
2415
2500
 
@@ -2768,11 +2853,12 @@ declare function failedPaymentTx(error: CheckoutError | null | undefined): strin
2768
2853
  /**
2769
2854
  * What the checkout says about a payment that left the wallet, or may have, from the store's error: a transaction that
2770
2855
  * does not pay the invoice (`pay.mismatch`; `pay.mismatchTakenElsewhere` when Quasar credited it to another invoice;
2771
- * `pay.mismatchHeldElsewhere` when another invoice holds it for a refund only, `held`;
2772
- * `pay.mismatchOtherWallet` for a transfer from a wallet that did not confirm the invoice, `pay.mismatchOtherWalletHeld`
2773
- * when Quasar recorded it as a held transfer the seller returns, `held`; `pay.mismatchNoReferenceHeld` for a Solana Pay
2774
- * transfer without the invoice's reference held on this invoice, `held`; `pay.mismatchChargeHeld` for a payment sent
2775
- * under an earlier price of the invoice, `quote_changed`), a payment Quasar closed after 24 hours without a result on chain
2856
+ * `pay.mismatchUnmatchedElsewhere` when it is an unmatched transfer at another invoice, refunded only, `unmatched`;
2857
+ * `pay.mismatchOtherWallet` for a transfer from a wallet that did not confirm the invoice,
2858
+ * `pay.mismatchOtherWalletUnmatched` when Quasar recorded it as an unmatched transfer the seller returns, `unmatched`;
2859
+ * `pay.mismatchNoReferenceUnmatched` for a Solana Pay transfer without the invoice's reference recorded on this
2860
+ * invoice, `unmatched`; `pay.mismatchChargeUnmatched` for a payment sent under an earlier price of the invoice,
2861
+ * `quote_changed`), a payment Quasar closed after 24 hours without a result on chain
2776
2862
  * (`outcome.unconfirmedClosed`), a transaction another invoice handed over first (`outcome.unconfirmedTakenElsewhere`)
2777
2863
  * and a payment the network confirmed that Quasar has not recorded yet (`outcome.unconfirmedSettlementRetrying` while
2778
2864
  * Quasar settles it again daily, for 30 days, else `outcome.unconfirmedSettlementFailed`). Never "it failed", "only the
@@ -2925,9 +3011,9 @@ declare function lockPrice(store: LockPriceStore, showConfirmWallet: (show: bool
2925
3011
  */
2926
3012
  declare function isPayerProofError(error: CheckoutError | null | undefined): boolean;
2927
3013
  /**
2928
- * Whether an error belongs on the step that confirms the wallet. The store's error may be about something else: a
2929
- * transfer held from another wallet, or a price refused to the last wallet, opened the step with "Something went wrong"
2930
- * before the wallet was asked anything.
3014
+ * Whether an error belongs on the step that confirms the wallet. The store's error may be about something else: an
3015
+ * unmatched transfer from another wallet, or a price refused to the last wallet, opened the step with "Something went
3016
+ * wrong" before the wallet was asked anything.
2931
3017
  *
2932
3018
  * @param error - The checkout store's error, if any.
2933
3019
  * @returns `true` for a refusal of the confirmation or a failure of its requests.
@@ -2998,5 +3084,5 @@ declare function invoiceTotals(invoice: CheckoutView['invoice']): {
2998
3084
  total: string;
2999
3085
  };
3000
3086
 
3001
- export { AmountStep, 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, balanceShortfall, baseUnitsToDecimal, buyerFields, buyerIssues, checkoutClassName, checkoutScreen, checkoutSteps, cleanBuyer, contactHref, countryOptions, deadlineAnnouncement, deadlineState, failedPaymentTx, formatCountdown, formatFeeAmount, formatFiat, formatTokenAmount, 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, 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 };
3002
- export type { 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 };
3087
+ export { AmountStep, 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, PayeeScreen, PaymentCheckout, PaymentFamily, PaymentWalletError, PaymentsAdapter, QUOTE_WARNING_MS, QrScreen, RefundButton, RefundDialog, RefundSteps, ScreenBody, SellerDetailsContent, SummaryFooter, WalletPrompt, addressOfWallet, balanceShortfall, baseUnitsToDecimal, buyerFields, buyerIssues, checkoutClassName, checkoutScreen, checkoutSteps, cleanBuyer, contactHref, countryOptions, deadlineAnnouncement, deadlineState, failedPaymentTx, formatCountdown, formatFeeAmount, formatFiat, formatTokenAmount, 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, payeeStatus, payeeVerified, payerProofErrorText, paymentFailedText, qrPath, quoteAmounts, quoteRate, receivedAmount, refundRateMoved, refundTransfer, refusalText, restRateText, screensPayingWallets, sentBeforeDeadline, shownLocale, unconfirmedFollowUp, unconfirmedTxKey, underpaidRest, useAsyncValue, useAutoReturn, useCheckoutContext, useCheckoutEvents, useCheckoutState, useCheckoutStore, useConnectedWallet, useNovaPayments, useNow, useOptionalCheckoutContext, usePaidCallback, usePayerProof, usePayment, usePaymentFacts, usePaymentHandOver, usePaymentsConnection, usePaymentsLabels, useRefund, useRereadValue, useWalletConnection, verifyPayeeWith, walletErrorKind, walletOnConfirmStep };
3088
+ export type { 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, PayeeStatus, 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 };