@tuwaio/payments-sdk 0.0.0 → 0.0.1

package/dist/types-Bp6JUt56.d-ByIsb1F7.d.cts

@@ -0,0 +1,350 @@
+import { Transaction } from '@tuwaio/sdk/pulsar';
+import { P as PaymentInstructions, T as TransferAuthorizationTypedData, m as PermissionRequest, G as GrantPermissionParams, f as CheckoutMethod } from './checkout-C05-kSiE.cjs';
+
+/**
+ * @file The connected wallet and the payment methods as the method step needs them: CAIP identifiers, the payer of a
+ * method, QR payments, discounts and markups.
+ */
+
+/** The chain family of a payment method or wallet. */
+type PaymentFamily = 'eip155' | 'solana';
+/** The wallet connected through Satellite Connect, as the checkout uses it. */
+interface CheckoutWallet {
+    /** The account address. */
+    address: string;
+    /** CAIP-2 chain the wallet is on (Solana clusters as their genesis-hash ID). */
+    chainId: string;
+    /** Its chain family. */
+    family: PaymentFamily;
+    /** Connector type of Satellite Connect (`evm:metamask`). */
+    connectorType: string;
+    /** The wallet id for `WalletIcon` of `@tuwaio/nova-core` (`metamask`). */
+    walletId: string;
+    /** The wallet name to show: the name the wallet gives itself (`Switch Wallet`), see {@link walletLabel}. */
+    name: string;
+    /**
+     * The icon the wallet gives itself, an image `data:` URI (EIP-6963, Wallet Standard) or an HTTPS URL: of the
+     * connection (the connector that connected), else of its wallet in the Satellite store; `undefined` when neither
+     * gives one the checkout can show, and the checkout shows the icon of `walletId`.
+     */
+    icon?: string;
+    /** The Satellite Connect connection itself, for the chain adapters (the Solana adapter signs with its account). */
+    connection: unknown;
+}
+/**
+ * The name of a wallet: the name it gives itself, as the wallet list of Nova Connect shows it (`Switch Wallet`);
+ * without one, the name Nova knows for its connector type (`evm:metamask` is `MetaMask`), else the connector type
+ * with a capital letter. The generic injected connector is always `Browser wallet`.
+ *
+ * @param connectorType - Connector type of Satellite Connect, for example `evm:metamask`.
+ * @param ownName - The name of the wallet's connector (`name` of the wagmi connector or the Wallet Standard wallet).
+ * @returns The name, for example `MetaMask`.
+ */
+declare function walletLabel(connectorType: string, ownName?: string): string;
+/**
+ * Whether the checkout shows an icon a wallet gives itself: an image `data:` URI (EIP-6963, Wallet Standard) or an
+ * HTTPS URL.
+ *
+ * @param icon - The icon.
+ * @returns `true` for an image `data:` URI or an HTTPS URL.
+ * @internal
+ */
+declare const isWalletIconUrl: (icon: string) => boolean;
+/**
+ * The family of a CAIP-2 chain.
+ *
+ * @param chainId - A CAIP-2 chain ID.
+ * @returns `eip155` or `solana`; `null` for another namespace.
+ */
+declare const familyOf: (chainId: string) => PaymentFamily | null;
+/**
+ * The connected wallet of Satellite Connect in CAIP identifiers, named and shown as the wallet calls itself.
+ *
+ * @param connection - The active connection of the Satellite store: `address`, `chainId` (an EVM number or a Solana
+ * cluster), `connectorType`, and the `icon` of the wallet when the adapter set it.
+ * @param connectors - The wallets of the Satellite store by adapter (`getConnectors()`): the one with the connector
+ * type of the connection gives the name (see {@link walletLabel}); of several such wallets, the one with the icon of
+ * the connection. When it is not listed, the name comes from the connector type. The icon is the connection's, else
+ * the listed wallet's, when it is an image `data:` URI or an HTTPS URL.
+ * @returns The wallet, or `null` without a connection or with a chain the checkout cannot read.
+ */
+declare function connectedWallet(connection: {
+    address: string;
+    chainId: string | number;
+    connectorType: string;
+    icon?: string;
+} | null | undefined, connectors?: Partial<Record<string, unknown[]>>): CheckoutWallet | null;
+/**
+ * The chain family of a payment method.
+ *
+ * @param method - The method.
+ * @returns `eip155` or `solana`; `null` for another namespace.
+ */
+declare function methodFamily(method: CheckoutMethod): PaymentFamily | null;
+/**
+ * The payer of a method for the connected wallet: its address on the method's chain. A wallet of the other family
+ * cannot pay it; a wallet on another chain of the family pays after switching (the quote names the method's chain).
+ *
+ * @param wallet - The connected wallet.
+ * @param method - The method.
+ * @returns The CAIP-10 account, or `null`.
+ */
+declare function payerFor(wallet: CheckoutWallet | null, method: CheckoutMethod): string | null;
+/**
+ * Whether a method can be paid by scanning a QR code with a phone: Solana with Solana Pay, an EVM method only through
+ * the payment page opened on the phone.
+ *
+ * @param method - The method.
+ * @param payUrl - The payment page of the invoice (its `payUrl`), if the app has it.
+ * @returns Whether the QR option applies.
+ */
+declare function canPayWithQr(method: CheckoutMethod, payUrl?: string | null): boolean;
+/**
+ * The discount or markup of a method, as the token and network options show it.
+ *
+ * @param method - The method.
+ * @returns `discount` or `markup` with the percent (`'1.5'`), or `null` for neither.
+ */
+declare function priceAdjustment(method: CheckoutMethod): {
+    kind: 'discount' | 'markup';
+    percent: string;
+} | null;
+/**
+ * The name of a method's network, from the chain names of `@tuwaio/nova-core`.
+ *
+ * @param chainId - CAIP-2 chain of the method (`eip155:8453`, `solana:EtWT…`).
+ * @returns The name (`Base`, `Solana Devnet`), `Unknown` for a chain nova-core does not list.
+ */
+declare function networkName(chainId: string): string;
+/**
+ * The token of a method as a chain reads its balance, from its CAIP-19 asset.
+ *
+ * @param method - The payment method.
+ * @returns The token contract or mint, or `native` for the coin of the chain (a `slip44` asset, or none).
+ */
+declare function methodToken(method: CheckoutMethod): string;
+
+/** A fee in the native coin of a chain, in its base units. */
+interface NativeFee {
+    /** The amount, in base units. */
+    amount: bigint;
+    /** Decimals of the native coin. */
+    decimals: number;
+    /** Symbol of the native coin. */
+    symbol: string;
+}
+/** A payment the wallet sent, with the texts of its transaction, for {@link PaymentsAdapter.pulsarTransaction}. */
+interface PulsarTransactionParams {
+    /** The transaction hash (EVM) or signature (Solana). */
+    txKey: string;
+    /** What the wallet sent. */
+    instructions: PaymentInstructions;
+    /** The sender. */
+    account: string;
+    /** The connector of the wallet (`evm:metamask`). */
+    connectorType: string;
+    /** Title of the transaction (at most 100 characters). */
+    title: string;
+    /** Description of the transaction (at most 300 characters). */
+    description: string;
+    /** What the transaction pays: `quasarInvoice` is the invoice ID. */
+    payload: Record<string, string>;
+}
+/**
+ * What the checkout needs from a chain family to pay from the connected wallet. `@tuwaio/nova-payments/evm` and
+ * `@tuwaio/nova-payments/solana` make them; the checkout itself imports no chain library. Chains are CAIP-2 IDs, and
+ * amounts base units. A method that fails because of the wallet throws `PaymentWalletError` (or the wallet library's
+ * error, which the checkout reads with `walletErrorKind`).
+ */
+interface PaymentsAdapter {
+    /** The chain family it pays on. */
+    family: PaymentFamily;
+    /**
+     * Reads a balance from the network in the browser (no request to Quasar).
+     *
+     * @param params - The chain, the account and the token (`native` for the coin of the chain).
+     * @returns The balance, in base units.
+     */
+    getBalance: (params: {
+        chainId: string;
+        account: string;
+        token: string;
+    }) => Promise<bigint>;
+    /**
+     * Estimates the network fee of the transfer, paid in the native coin.
+     *
+     * @param params - What the wallet sends and the sender.
+     * @returns The fee, or `null` when it cannot be estimated.
+     */
+    estimateFee?: (params: {
+        instructions: PaymentInstructions;
+        account: string;
+    }) => Promise<NativeFee | null>;
+    /**
+     * Whether the wallet sends `wallet_sendCalls` with the `paymasterService` capability on the chain (EIP-5792,
+     * ERC-7677).
+     *
+     * @param params - The chain and the account.
+     * @returns `true` when sponsored calls are possible.
+     */
+    canSponsorCalls?: (params: {
+        chainId: string;
+        account: string;
+    }) => Promise<boolean>;
+    /**
+     * Asks the wallet to switch to the chain of the payment.
+     *
+     * @param chainId - The chain.
+     */
+    switchChain?: (chainId: string) => Promise<void>;
+    /**
+     * Sends the transfer the quote describes, with the wallet's prompt.
+     *
+     * @param params - The quote's instructions, the sender, and the Satellite Connect connection of the wallet (the
+     *   Solana adapter signs with its Wallet Standard account).
+     * @returns The transaction hash (EVM) or signature (Solana).
+     */
+    sendTransfer: (params: {
+        instructions: PaymentInstructions;
+        account: string;
+        connection?: unknown;
+    }) => Promise<string>;
+    /**
+     * Signs the EIP-3009 authorization of a gasless quote (`eth_signTypedData_v4`), with the wallet's prompt.
+     *
+     * @param params - The typed data and the signer.
+     * @returns The 65-byte signature.
+     */
+    signTransferAuthorization?: (params: {
+        typedData: TransferAuthorizationTypedData;
+        account: string;
+    }) => Promise<string>;
+    /**
+     * Signs a message with `personal_sign` (EIP-191), with the wallet's prompt: the EIP-4361 message by which the paying
+     * wallet confirms the invoice before an EVM payment it sends itself (`confirmPayer` of the checkout store of
+     * `@tuwaio/quasar-sdk/checkout`). A free signature that moves no funds; a smart wallet signs it through its own flow
+     * (ERC-1271, ERC-6492), often with a passkey. Without it the checkout cannot pay methods that need the confirmation
+     * from this wallet.
+     *
+     * @param params - The message exactly as Quasar wrote it, the signer, and the CAIP-2 network the message names (the
+     *   wallet is on it already: the checkout switches it first).
+     * @returns The signature, as hex.
+     */
+    signMessage?: (params: {
+        message: string;
+        account: string;
+        chainId: string;
+    }) => Promise<string>;
+    /**
+     * Sends the sponsored calls of a gasless quote with `wallet_sendCalls` and the paymaster, with the wallet's prompt,
+     * and waits for the transaction that carries them.
+     *
+     * @param params - The calls, the paymaster URL of the checkout, the chain, the sender, and `onSent`, called once the
+     *   wallet accepted the calls (before they are included).
+     * @returns The hash of the transaction (not the batch ID), as Quasar expects it.
+     */
+    /**
+     * The link of a transaction on a block explorer of its chain.
+     *
+     * @param params - The chain and the transaction hash or signature.
+     * @returns The link, or `undefined` when the chain has no known explorer.
+     */
+    explorerUrl?: (params: {
+        chainId: string;
+        txKey: string;
+    }) => string | undefined;
+    /**
+     * The link of a wallet address on a block explorer of its chain.
+     *
+     * @param params - The chain and the address.
+     * @returns The link, or `undefined` when the chain has no known explorer.
+     */
+    explorerAddressUrl?: (params: {
+        chainId: string;
+        address: string;
+    }) => string | undefined;
+    /**
+     * What the account is for automatic payments, read before asking for the permission: `smart` has code on the network,
+     * `upgradable` is a plain account its wallet can switch to a smart account, `unknown` says nothing either way. Quasar
+     * decides in the end: it refuses a wallet that could never be charged.
+     *
+     * @param params - The network and the account.
+     * @returns The kind.
+     */
+    smartAccountStatus?: (params: {
+        chainId: string;
+        account: string;
+    }) => Promise<'smart' | 'upgradable' | 'unknown'>;
+    /**
+     * Has the wallet switch a plain account to its smart account (`upgradable` of {@link PaymentsAdapter.smartAccountStatus})
+     * and waits until the network includes it. The wallet asks the buyer and the buyer pays the network fee.
+     *
+     * @param params - The network and the account.
+     */
+    upgradeToSmartAccount?: (params: {
+        chainId: string;
+        account: string;
+    }) => Promise<void>;
+    /**
+     * Asks the wallet for the ERC-7715 permission of a subscription's automatic payments, with the wallet's prompt.
+     *
+     * @param params - The request of the checkout's auto-charge offer and the granting account.
+     * @returns What the wallet granted, for `grantPermission` of the checkout store (without the payer).
+     */
+    requestPermission?: (params: {
+        request: PermissionRequest;
+        account: string;
+    }) => Promise<Omit<GrantPermissionParams, 'payer'>>;
+    /**
+     * Sends the transaction that revokes the permission of a subscription's automatic payments, with the wallet's prompt,
+     * and waits until the network includes it. The wallet pays its network fee.
+     *
+     * @param params - The transaction of the checkout's auto-charge offer, its CAIP-2 chain, the account that granted the
+     * permission and what to call once the wallet has sent it: a failure while waiting must not send it again.
+     */
+    revokePermission?: (params: {
+        revocation: {
+            to: string;
+            data: string;
+        };
+        chainId: string;
+        account: string;
+        onSent?: () => void;
+    }) => Promise<void>;
+    /**
+     * Describes a sent payment as a pending transaction of `@tuwaio/pulsar-core`, so that the app's Pulsar store tracks
+     * it (and Nova Transactions shows its toast) once the checkout closes.
+     *
+     * @param params - The payment and the texts of its transaction.
+     * @returns The pending transaction, for `injectExternalPendingTxs` of the Pulsar store.
+     */
+    pulsarTransaction?: (params: PulsarTransactionParams) => Transaction;
+    /**
+     * Follows a batch the wallet took before the page was reloaded, until its transaction comes or `until` passes.
+     *
+     * @param params - The batch, until when to follow it (a timestamp) and what to call with its transaction.
+     */
+    followSponsoredCalls?: (params: {
+        batchId: string;
+        until: number;
+        onLate: (txKey: string) => void;
+    }) => void;
+    sendSponsoredCalls?: (params: {
+        calls: {
+            to: string;
+            value: string;
+            data: string;
+        }[];
+        paymasterUrl: string;
+        chainId: string;
+        account: string;
+        onSent?: () => void;
+        /** Called with the ID of the batch as soon as the wallet took it, before it has a transaction. */
+        onAccepted?: (batchId: string) => void;
+        /** Called with the transaction of a batch that landed after the adapter gave up waiting (`sentUnconfirmed`). */
+        onLate?: (txKey: string) => void;
+    }) => Promise<string>;
+}
+
+export { canPayWithQr as c, connectedWallet as d, methodToken as e, familyOf as f, priceAdjustment as g, isWalletIconUrl as i, methodFamily as m, networkName as n, payerFor as p, walletLabel as w };
+export type { CheckoutWallet as C, NativeFee as N, PaymentsAdapter as P, PaymentFamily as a, PulsarTransactionParams as b };