@tuwaio/nova-payments 0.4.0 → 0.5.1

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 +109 -12
  17. package/dist/index.d.ts +109 -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,15 @@ 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. A `payUrl` without pins of its own gets
1050
+ * them for the phone it is handed to (the QR code of an EVM method).
1051
+ */
1052
+ payoutAddresses?: readonly string[];
1040
1053
  /**
1041
1054
  * Connects a wallet of a chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1042
1055
  * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection of `NovaPaymentsProvider`)
@@ -1122,7 +1135,7 @@ declare function CheckoutFrame({ className, withDetails, leave, }: {
1122
1135
  * }
1123
1136
  * ```
1124
1137
  */
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;
1138
+ 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
1139
  /**
1127
1140
  * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1128
1141
  * no step can move its top.
@@ -1446,6 +1459,84 @@ declare function MethodScreen(): react.JSX.Element | null;
1446
1459
  */
1447
1460
  declare function PaidScreen(): react.JSX.Element | null;
1448
1461
 
1462
+ /**
1463
+ * @file The payee of the quote the checkout shows: where the store's check of it stands, and the check of its payout
1464
+ * record's signature by the chain adapters. The checkout shows a quote's address and asks the wallet to pay only once
1465
+ * the store verified this very quote (`payee` of `createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`).
1466
+ */
1467
+
1468
+ /**
1469
+ * Where the check of the shown quote's payee stands: `checking` until the store checked this very quote (also while
1470
+ * it still holds the check of an earlier quote), then `verified` or `refused`.
1471
+ */
1472
+ type PayeeStatus = {
1473
+ status: 'checking';
1474
+ } | {
1475
+ status: 'verified';
1476
+ } | {
1477
+ status: 'refused';
1478
+ reason: PayeeRefusal;
1479
+ };
1480
+ /**
1481
+ * Where the check of the quote's payee stands, from the checkout store's state.
1482
+ *
1483
+ * @param state - `quote` and `payeeCheck` of the checkout store.
1484
+ * @returns The status for this very quote: a check of another quote counts as `checking`.
1485
+ */
1486
+ declare function payeeStatus(state: {
1487
+ quote?: CheckoutQuote | null;
1488
+ payeeCheck?: PayeeCheck | null;
1489
+ }): PayeeStatus;
1490
+ /**
1491
+ * Whether the store verified the payee of this very quote: the only state in which the checkout sends a payment.
1492
+ *
1493
+ * @param state - `quote` and `payeeCheck` of the checkout store.
1494
+ * @param quote - The quote about to be paid.
1495
+ * @returns `true` once the store's check of this quote found its payee verified.
1496
+ */
1497
+ declare function payeeVerified(state: {
1498
+ payeeCheck?: PayeeCheck | null;
1499
+ }, quote: CheckoutQuote): boolean;
1500
+ /**
1501
+ * Checks the signature of a quote's payout record with the adapter of its chain family (`verifyPayoutRecord`): the
1502
+ * {@link PayeeVerifier} of a checkout over its adapters.
1503
+ *
1504
+ * Side effects: on EVM, a smart wallet's signature is put to its contract through the app's RPC.
1505
+ *
1506
+ * @param adapters - The checkout's payment adapters.
1507
+ * @param params - The record, its signature and the network (CAIP-2) of the quote.
1508
+ * @returns Whether the signature holds, or `null` when no adapter of the family checks signatures.
1509
+ */
1510
+ declare function verifyPayeeWith(adapters: readonly PaymentsAdapter[] | undefined, params: Parameters<PayeeVerifier>[0]): Promise<boolean | null>;
1511
+ /**
1512
+ * The payment page a phone opens (the QR code of an EVM method), with the merchant's pinned payout addresses: a link
1513
+ * that carries none gets those of the checkout, so the checkout on the phone refuses the same addresses as this one. A
1514
+ * link with pins of its own (from the server SDK) stays as it is.
1515
+ *
1516
+ * @param payUrl - The payment page of the invoice, if the app has it.
1517
+ * @param payoutAddresses - The merchant's pinned payout addresses of the checkout (`payoutAddresses`).
1518
+ * @returns The link to hand over.
1519
+ */
1520
+ declare function handOffPayUrl(payUrl: string | null | undefined, payoutAddresses: readonly string[] | undefined): string | null | undefined;
1521
+
1522
+ /**
1523
+ * What the pay and QR steps show instead of the payment until the checkout store verified the payee of the quote. While
1524
+ * the check runs, a wait that appears only when it takes more than a moment: an ordinary wallet's signature is checked
1525
+ * in the page at once, a smart wallet's asks its contract on the network. When the address could not be confirmed as
1526
+ * the merchant's, a refusal: the address is never shown and the wallet never asked, whatever the reason, which
1527
+ * `data-payee-refusal` names for the integrator (`payee_unsigned`, `payee_mismatch`, `payee_not_pinned`,
1528
+ * `payee_unverified`).
1529
+ *
1530
+ * @param props - Where the check stands.
1531
+ * @param props.payee - `checking`, or `refused` with its reason ({@link payeeStatus}).
1532
+ * @returns The step.
1533
+ */
1534
+ declare function PayeeScreen({ payee }: {
1535
+ payee: Exclude<PayeeStatus, {
1536
+ status: 'verified';
1537
+ }>;
1538
+ }): react.JSX.Element;
1539
+
1449
1540
  /**
1450
1541
  * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
1451
1542
  * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
@@ -1882,10 +1973,16 @@ interface UseCheckoutStoreOptions {
1882
1973
  pollMs?: number;
1883
1974
  /** Whether to load and follow the invoice; `false` keeps the idle store, which makes no requests. Defaults to `true`. */
1884
1975
  enabled?: boolean;
1976
+ /**
1977
+ * How the store checks the payee of each quote (`payee` of `createCheckoutStore`): the signature verifier, read when
1978
+ * the store is created, and the merchant's pinned addresses, whose change makes the store again, so that no quote is
1979
+ * checked against pins the page has since replaced.
1980
+ */
1981
+ payee?: PayeeOptions;
1885
1982
  }
1886
1983
  /**
1887
1984
  * 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`
1985
+ * 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
1986
  * phase that makes no requests.
1890
1987
  *
1891
1988
  * Side effects: the store reads the checkout and follows the invoice (an `EventSource` on its `events` route, or a
@@ -2365,9 +2462,9 @@ declare function instructionsChainId(instructions: PaymentInstructions): string;
2365
2462
  interface PayInvoiceParams {
2366
2463
  /** The adapter of the quote's chain family. */
2367
2464
  adapter: PaymentsAdapter;
2368
- /** The checkout store (only `submit`, `relay` and `relayFromPage` are used). */
2465
+ /** The checkout store (only `submit`, `relay`, `relayFromPage` and `payeeCheck` are used). */
2369
2466
  store: {
2370
- getState: () => Pick<CheckoutState, 'submit' | 'relay'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2467
+ getState: () => Pick<CheckoutState, 'submit' | 'relay' | 'payeeCheck'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2371
2468
  };
2372
2469
  /** The locked quote. */
2373
2470
  quote: CheckoutQuote;
@@ -2407,8 +2504,8 @@ interface PayInvoiceParams {
2407
2504
  *
2408
2505
  * @param params - See {@link PayInvoiceParams}.
2409
2506
  * @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.
2507
+ * @throws {@link PaymentWalletError} `unsupported` when the store has not verified the payee of this quote
2508
+ * (`payeeCheck`), or the adapter or the quote cannot take the path; the wallet's error when it refuses or fails.
2412
2509
  */
2413
2510
  declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onBatchAccepted, onSent, }: PayInvoiceParams): Promise<boolean>;
2414
2511
 
@@ -2998,5 +3095,5 @@ declare function invoiceTotals(invoice: CheckoutView['invoice']): {
2998
3095
  total: string;
2999
3096
  };
3000
3097
 
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 };
3098
+ 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, handOffPayUrl, 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 };
3099
+ 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,15 @@ 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. A `payUrl` without pins of its own gets
1050
+ * them for the phone it is handed to (the QR code of an EVM method).
1051
+ */
1052
+ payoutAddresses?: readonly string[];
1040
1053
  /**
1041
1054
  * Connects a wallet of a chain family, for apps without Nova Connect; overrides the `onConnectWallet` of
1042
1055
  * `NovaPaymentsProvider`. Inside `NovaConnectProvider` (the app's, or Nova's own connection of `NovaPaymentsProvider`)
@@ -1122,7 +1135,7 @@ declare function CheckoutFrame({ className, withDetails, leave, }: {
1122
1135
  * }
1123
1136
  * ```
1124
1137
  */
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;
1138
+ 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
1139
  /**
1127
1140
  * The checkout as a whole page: the block, centered from a floor (`styles/app.css`) and not from its own height, so that
1128
1141
  * no step can move its top.
@@ -1446,6 +1459,84 @@ declare function MethodScreen(): react.JSX.Element | null;
1446
1459
  */
1447
1460
  declare function PaidScreen(): react.JSX.Element | null;
1448
1461
 
1462
+ /**
1463
+ * @file The payee of the quote the checkout shows: where the store's check of it stands, and the check of its payout
1464
+ * record's signature by the chain adapters. The checkout shows a quote's address and asks the wallet to pay only once
1465
+ * the store verified this very quote (`payee` of `createCheckoutStore` from `@tuwaio/quasar-sdk/checkout`).
1466
+ */
1467
+
1468
+ /**
1469
+ * Where the check of the shown quote's payee stands: `checking` until the store checked this very quote (also while
1470
+ * it still holds the check of an earlier quote), then `verified` or `refused`.
1471
+ */
1472
+ type PayeeStatus = {
1473
+ status: 'checking';
1474
+ } | {
1475
+ status: 'verified';
1476
+ } | {
1477
+ status: 'refused';
1478
+ reason: PayeeRefusal;
1479
+ };
1480
+ /**
1481
+ * Where the check of the quote's payee stands, from the checkout store's state.
1482
+ *
1483
+ * @param state - `quote` and `payeeCheck` of the checkout store.
1484
+ * @returns The status for this very quote: a check of another quote counts as `checking`.
1485
+ */
1486
+ declare function payeeStatus(state: {
1487
+ quote?: CheckoutQuote | null;
1488
+ payeeCheck?: PayeeCheck | null;
1489
+ }): PayeeStatus;
1490
+ /**
1491
+ * Whether the store verified the payee of this very quote: the only state in which the checkout sends a payment.
1492
+ *
1493
+ * @param state - `quote` and `payeeCheck` of the checkout store.
1494
+ * @param quote - The quote about to be paid.
1495
+ * @returns `true` once the store's check of this quote found its payee verified.
1496
+ */
1497
+ declare function payeeVerified(state: {
1498
+ payeeCheck?: PayeeCheck | null;
1499
+ }, quote: CheckoutQuote): boolean;
1500
+ /**
1501
+ * Checks the signature of a quote's payout record with the adapter of its chain family (`verifyPayoutRecord`): the
1502
+ * {@link PayeeVerifier} of a checkout over its adapters.
1503
+ *
1504
+ * Side effects: on EVM, a smart wallet's signature is put to its contract through the app's RPC.
1505
+ *
1506
+ * @param adapters - The checkout's payment adapters.
1507
+ * @param params - The record, its signature and the network (CAIP-2) of the quote.
1508
+ * @returns Whether the signature holds, or `null` when no adapter of the family checks signatures.
1509
+ */
1510
+ declare function verifyPayeeWith(adapters: readonly PaymentsAdapter[] | undefined, params: Parameters<PayeeVerifier>[0]): Promise<boolean | null>;
1511
+ /**
1512
+ * The payment page a phone opens (the QR code of an EVM method), with the merchant's pinned payout addresses: a link
1513
+ * that carries none gets those of the checkout, so the checkout on the phone refuses the same addresses as this one. A
1514
+ * link with pins of its own (from the server SDK) stays as it is.
1515
+ *
1516
+ * @param payUrl - The payment page of the invoice, if the app has it.
1517
+ * @param payoutAddresses - The merchant's pinned payout addresses of the checkout (`payoutAddresses`).
1518
+ * @returns The link to hand over.
1519
+ */
1520
+ declare function handOffPayUrl(payUrl: string | null | undefined, payoutAddresses: readonly string[] | undefined): string | null | undefined;
1521
+
1522
+ /**
1523
+ * What the pay and QR steps show instead of the payment until the checkout store verified the payee of the quote. While
1524
+ * the check runs, a wait that appears only when it takes more than a moment: an ordinary wallet's signature is checked
1525
+ * in the page at once, a smart wallet's asks its contract on the network. When the address could not be confirmed as
1526
+ * the merchant's, a refusal: the address is never shown and the wallet never asked, whatever the reason, which
1527
+ * `data-payee-refusal` names for the integrator (`payee_unsigned`, `payee_mismatch`, `payee_not_pinned`,
1528
+ * `payee_unverified`).
1529
+ *
1530
+ * @param props - Where the check stands.
1531
+ * @param props.payee - `checking`, or `refused` with its reason ({@link payeeStatus}).
1532
+ * @returns The step.
1533
+ */
1534
+ declare function PayeeScreen({ payee }: {
1535
+ payee: Exclude<PayeeStatus, {
1536
+ status: 'verified';
1537
+ }>;
1538
+ }): react.JSX.Element;
1539
+
1449
1540
  /**
1450
1541
  * The pay step: the connected wallet (with "Change"), the exact amount to send with its network and invoice value,
1451
1542
  * the price lock with "Keep this price" in its last minute, the rate, the network fee (the merchant's or an estimate),
@@ -1882,10 +1973,16 @@ interface UseCheckoutStoreOptions {
1882
1973
  pollMs?: number;
1883
1974
  /** Whether to load and follow the invoice; `false` keeps the idle store, which makes no requests. Defaults to `true`. */
1884
1975
  enabled?: boolean;
1976
+ /**
1977
+ * How the store checks the payee of each quote (`payee` of `createCheckoutStore`): the signature verifier, read when
1978
+ * the store is created, and the merchant's pinned addresses, whose change makes the store again, so that no quote is
1979
+ * checked against pins the page has since replaced.
1980
+ */
1981
+ payee?: PayeeOptions;
1885
1982
  }
1886
1983
  /**
1887
1984
  * 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`
1985
+ * 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
1986
  * phase that makes no requests.
1890
1987
  *
1891
1988
  * Side effects: the store reads the checkout and follows the invoice (an `EventSource` on its `events` route, or a
@@ -2365,9 +2462,9 @@ declare function instructionsChainId(instructions: PaymentInstructions): string;
2365
2462
  interface PayInvoiceParams {
2366
2463
  /** The adapter of the quote's chain family. */
2367
2464
  adapter: PaymentsAdapter;
2368
- /** The checkout store (only `submit`, `relay` and `relayFromPage` are used). */
2465
+ /** The checkout store (only `submit`, `relay`, `relayFromPage` and `payeeCheck` are used). */
2369
2466
  store: {
2370
- getState: () => Pick<CheckoutState, 'submit' | 'relay'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2467
+ getState: () => Pick<CheckoutState, 'submit' | 'relay' | 'payeeCheck'> & Partial<Pick<CheckoutState, 'relayFromPage'>>;
2371
2468
  };
2372
2469
  /** The locked quote. */
2373
2470
  quote: CheckoutQuote;
@@ -2407,8 +2504,8 @@ interface PayInvoiceParams {
2407
2504
  *
2408
2505
  * @param params - See {@link PayInvoiceParams}.
2409
2506
  * @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.
2507
+ * @throws {@link PaymentWalletError} `unsupported` when the store has not verified the payee of this quote
2508
+ * (`payeeCheck`), or the adapter or the quote cannot take the path; the wallet's error when it refuses or fails.
2412
2509
  */
2413
2510
  declare function payInvoice({ adapter, store, quote, wallet, path, paymasterUrl, onWalletDone, onBatchAccepted, onSent, }: PayInvoiceParams): Promise<boolean>;
2414
2511
 
@@ -2998,5 +3095,5 @@ declare function invoiceTotals(invoice: CheckoutView['invoice']): {
2998
3095
  total: string;
2999
3096
  };
3000
3097
 
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 };
3098
+ 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, handOffPayUrl, 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 };
3099
+ 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 };