@tuwaio/nova-payments 0.4.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 +11 -0
  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 +98 -12
  17. package/dist/index.d.ts +98 -12
  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-BLbRvz3z.d.cts → locales-fU-NVESw.d.cts} +9 -0
  22. package/dist/{locales-BLbRvz3z.d.ts → locales-fU-NVESw.d.ts} +9 -0
  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-5KGDZSPE.js +0 -1
  33. package/dist/chunk-A52KWC4O.cjs +0 -1
  34. package/dist/de-5EFHX2IO.js +0 -1
  35. package/dist/de-CBZGMJRL.cjs +0 -1
  36. package/dist/es-3BS5SMKZ.js +0 -1
  37. package/dist/es-OIY4CIB2.cjs +0 -1
  38. package/dist/it-RGYBW74Q.js +0 -1
  39. package/dist/it-YZLQZLZI.cjs +0 -1
  40. package/dist/uk-3KBDAAPC.cjs +0 -1
  41. package/dist/uk-TQG4B3QD.js +0 -1
  42. package/dist/zhCN-24WZ65H5.js +0 -1
  43. package/dist/zhCN-WVH73E5W.cjs +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';
@@ -827,7 +827,11 @@ interface PaymentCheckoutComponents {
827
827
  StatusIcon?: ComponentType<CheckoutStatusIconProps>;
828
828
  /** The strip and the wash of the status color along the top of the checkout (`StatusEdge` of `@tuwaio/nova-core`). */
829
829
  StatusEdge?: ComponentType<StatusEdgeProps>;
830
- /** 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
+ */
831
835
  screens?: Partial<Record<CheckoutScreen, ComponentType<CheckoutScreenProps>>>;
832
836
  }
833
837
  /**
@@ -1037,6 +1041,14 @@ interface PaymentCheckoutProps {
1037
1041
  * leaving it out offers the QR code for Solana methods only.
1038
1042
  */
1039
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[];
1040
1052
  /**
1041
1053
  * Connects a wallet of a chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1042
1054
  * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection of `NovaPaymentsProvider`)
@@ -1122,7 +1134,7 @@ declare function CheckoutFrame({ className, withDetails, leave, }: {
1122
1134
  * }
1123
1135
  * ```
1124
1136
  */
1125
- 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;
1126
1138
  /**
1127
1139
  * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1128
1140
  * no step can move its top.
@@ -1446,6 +1458,74 @@ declare function MethodScreen(): react.JSX.Element | null;
1446
1458
  */
1447
1459
  declare function PaidScreen(): react.JSX.Element | null;
1448
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
+
1449
1529
  /**
1450
1530
  * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
1451
1531
  * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
@@ -1882,10 +1962,16 @@ interface UseCheckoutStoreOptions {
1882
1962
  pollMs?: number;
1883
1963
  /** Whether to load and follow the invoice; `false` keeps the idle store, which makes no requests. Defaults to `true`. */
1884
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;
1885
1971
  }
1886
1972
  /**
1887
1973
  * The checkout store of an invoice (`createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`): created and loaded
1888
- * 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`
1889
1975
  * phase that makes no requests.
1890
1976
  *
1891
1977
  * Side effects: the store reads the checkout and follows the invoice (an `EventSource` on its `events` route, or a
@@ -2365,9 +2451,9 @@ declare function instructionsChainId(instructions: PaymentInstructions): string;
2365
2451
  interface PayInvoiceParams {
2366
2452
  /** The adapter of the quote's chain family. */
2367
2453
  adapter: PaymentsAdapter;
2368
- /** The checkout store (only `submit`, `relay` and `relayFromPage` are used). */
2454
+ /** The checkout store (only `submit`, `relay`, `relayFromPage` and `payeeCheck` are used). */
2369
2455
  store: {
2370
- getState: () => Pick<CheckoutState, 'submit' | 'relay'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2456
+ getState: () => Pick<CheckoutState, 'submit' | 'relay' | 'payeeCheck'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2371
2457
  };
2372
2458
  /** The locked quote. */
2373
2459
  quote: CheckoutQuote;
@@ -2407,8 +2493,8 @@ interface PayInvoiceParams {
2407
2493
  *
2408
2494
  * @param params - See {@link PayInvoiceParams}.
2409
2495
  * @returns Whether Quasar took the payment (the store's `error` says why not).
2410
- * @throws {@link PaymentWalletError} `unsupported` when the adapter or the quote cannot take the path; the wallet's
2411
- * 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.
2412
2498
  */
2413
2499
  declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onBatchAccepted, onSent, }: PayInvoiceParams): Promise<boolean>;
2414
2500
 
@@ -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';
@@ -827,7 +827,11 @@ interface PaymentCheckoutComponents {
827
827
  StatusIcon?: ComponentType<CheckoutStatusIconProps>;
828
828
  /** The strip and the wash of the status color along the top of the checkout (`StatusEdge` of `@tuwaio/nova-core`). */
829
829
  StatusEdge?: ComponentType<StatusEdgeProps>;
830
- /** 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
+ */
831
835
  screens?: Partial<Record<CheckoutScreen, ComponentType<CheckoutScreenProps>>>;
832
836
  }
833
837
  /**
@@ -1037,6 +1041,14 @@ interface PaymentCheckoutProps {
1037
1041
  * leaving it out offers the QR code for Solana methods only.
1038
1042
  */
1039
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[];
1040
1052
  /**
1041
1053
  * Connects a wallet of a chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1042
1054
  * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection of `NovaPaymentsProvider`)
@@ -1122,7 +1134,7 @@ declare function CheckoutFrame({ className, withDetails, leave, }: {
1122
1134
  * }
1123
1135
  * ```
1124
1136
  */
1125
- 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;
1126
1138
  /**
1127
1139
  * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1128
1140
  * no step can move its top.
@@ -1446,6 +1458,74 @@ declare function MethodScreen(): react.JSX.Element | null;
1446
1458
  */
1447
1459
  declare function PaidScreen(): react.JSX.Element | null;
1448
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
+
1449
1529
  /**
1450
1530
  * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
1451
1531
  * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
@@ -1882,10 +1962,16 @@ interface UseCheckoutStoreOptions {
1882
1962
  pollMs?: number;
1883
1963
  /** Whether to load and follow the invoice; `false` keeps the idle store, which makes no requests. Defaults to `true`. */
1884
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;
1885
1971
  }
1886
1972
  /**
1887
1973
  * The checkout store of an invoice (`createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`): created and loaded
1888
- * 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`
1889
1975
  * phase that makes no requests.
1890
1976
  *
1891
1977
  * Side effects: the store reads the checkout and follows the invoice (an `EventSource` on its `events` route, or a
@@ -2365,9 +2451,9 @@ declare function instructionsChainId(instructions: PaymentInstructions): string;
2365
2451
  interface PayInvoiceParams {
2366
2452
  /** The adapter of the quote's chain family. */
2367
2453
  adapter: PaymentsAdapter;
2368
- /** The checkout store (only `submit`, `relay` and `relayFromPage` are used). */
2454
+ /** The checkout store (only `submit`, `relay`, `relayFromPage` and `payeeCheck` are used). */
2369
2455
  store: {
2370
- getState: () => Pick<CheckoutState, 'submit' | 'relay'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2456
+ getState: () => Pick<CheckoutState, 'submit' | 'relay' | 'payeeCheck'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2371
2457
  };
2372
2458
  /** The locked quote. */
2373
2459
  quote: CheckoutQuote;
@@ -2407,8 +2493,8 @@ interface PayInvoiceParams {
2407
2493
  *
2408
2494
  * @param params - See {@link PayInvoiceParams}.
2409
2495
  * @returns Whether Quasar took the payment (the store's `error` says why not).
2410
- * @throws {@link PaymentWalletError} `unsupported` when the adapter or the quote cannot take the path; the wallet's
2411
- * 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.
2412
2498
  */
2413
2499
  declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onBatchAccepted, onSent, }: PayInvoiceParams): Promise<boolean>;
2414
2500
 
@@ -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 };