diff --git a/docs/react.airdropnftparams.md b/docs/react.airdropnftparams.md new file mode 100644 index 0000000..effd8a5 --- /dev/null +++ b/docs/react.airdropnftparams.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [AirdropNFTParams](./react.airdropnftparams.md) + +## AirdropNFTParams type + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The params to pass to `useTransferBatchNFT`. + +Signature: + +```typescript +export declare type AirdropNFTParams = { + tokenId: BigNumberish; + addresses: AirdropInput; +}; +``` diff --git a/docs/react.md b/docs/react.md index 530b15f..e8db641 100644 --- a/docs/react.md +++ b/docs/react.md @@ -15,6 +15,7 @@ import { useAddress } from "@thirdweb-dev/react" ``` | +| [useAirdropNFT(contract)](./react.useairdropnft.md) | (BETA) Use this to transfer tokens on your | | [useAllContractEvents(contract, options)](./react.useallcontractevents.md) | (BETA) Use this to query (and subscribe) to all events on a contract. | | [useAllRoleMembers(contract)](./react.useallrolemembers.md) | (BETA) Use this to get the roles of a | | [useAuctionWinner(contract, listingId)](./react.useauctionwinner.md) | (BETA) Use this to get the winner of an auction listing from your marketplace contract. | @@ -108,6 +109,7 @@ import { useNetworkMistmatch } from "@thirdweb-dev/react" | [useTotalCirculatingSupply(\[contract, tokenId\])](./react.usetotalcirculatingsupply.md) |

(BETA) Use this to get a the total (minted) supply of your [NFTContract](./react.nftcontract.md).

\*

| | [useTotalCount(contract)](./react.usetotalcount.md) | (BETA) Use this to get a the number of tokens in your [NFTContract](./react.nftcontract.md). | | [useTransferBatchToken(contract)](./react.usetransferbatchtoken.md) | (BETA) Use this to transfer batch tokens on your contract | +| [useTransferNFT(contract)](./react.usetransfernft.md) | (BETA) Use this to transfer tokens on your [NFTContract](./react.nftcontract.md) | | [useTransferToken(contract)](./react.usetransfertoken.md) | (BETA) Use this to transfer tokens on your contract | | [useUnclaimedNFTs(contract, queryParams)](./react.useunclaimednfts.md) | (BETA) Use this to get a list of \*unclaimed\* NFT tokens of your ERC721 Drop contract. | | [useUnclaimedNFTSupply(contract)](./react.useunclaimednftsupply.md) | | @@ -148,6 +150,7 @@ import { useWalletConnect } from "@thirdweb-dev/react" | Type Alias | Description | | --- | --- | +| [AirdropNFTParams](./react.airdropnftparams.md) | (BETA) The params to pass to useTransferBatchNFT. | | [BuyNowParams](./react.buynowparams.md) | | | [ClaimIneligibilityParameters](./react.claimineligibilityparameters.md) | (BETA) The options to be passed as the second parameter to the useClaimIneligibilityReasons hook. | | [ClaimNFTParams](./react.claimnftparams.md) | (BETA) The params for the [useClaimNFT()](./react.useclaimnft.md) hook mutation. | @@ -162,6 +165,7 @@ import { useWalletConnect } from "@thirdweb-dev/react" | [NFTContract](./react.nftcontract.md) | (BETA) The possible NFT contract types. | | [RequiredParam](./react.requiredparam.md) | (BETA) Makes a parameter required to be passed, but still allowes it to be undefined. | | [TokenParams](./react.tokenparams.md) | (BETA) The parameters to pass to the mint and transfer functions. | +| [TransferNFTParams](./react.transfernftparams.md) | (BETA) The params to pass to useTransferNFT. | | [useNFTBalanceParams](./react.usenftbalanceparams.md) | (BETA) The params to pass to useNftBalance. | | [useTotalCirculatingSupplyParams](./react.usetotalcirculatingsupplyparams.md) | (BETA) The params to pass to useTotalCirculatingSupply. | | [WalletAddress](./react.walletaddress.md) | (BETA) A wallet address. | diff --git a/docs/react.tokenparams.md b/docs/react.tokenparams.md index 0034cea..a3f5054 100644 --- a/docs/react.tokenparams.md +++ b/docs/react.tokenparams.md @@ -14,7 +14,7 @@ The parameters to pass to the mint and transfer functions. ```typescript export declare type TokenParams = { to: WalletAddress; - amount: string | number; + amount: Amount; }; ``` References: [WalletAddress](./react.walletaddress.md) diff --git a/docs/react.transfernftparams.md b/docs/react.transfernftparams.md new file mode 100644 index 0000000..fbe5d28 --- /dev/null +++ b/docs/react.transfernftparams.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [TransferNFTParams](./react.transfernftparams.md) + +## TransferNFTParams type + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The params to pass to `useTransferNFT`. + +Signature: + +```typescript +export declare type TransferNFTParams = TContract extends Erc1155 ? { + to: WalletAddress; + tokenId: BigNumberish; + amount: Amount; +} : { + to: WalletAddress; + tokenId: BigNumberish; +}; +``` +References: [WalletAddress](./react.walletaddress.md) + diff --git a/docs/react.useairdropnft.md b/docs/react.useairdropnft.md new file mode 100644 index 0000000..12ab603 --- /dev/null +++ b/docs/react.useairdropnft.md @@ -0,0 +1,91 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [useAirdropNFT](./react.useairdropnft.md) + +## useAirdropNFT() function + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Use this to transfer tokens on your + +Signature: + +```typescript +export declare function useAirdropNFT(contract: Erc1155): import("@tanstack/react-query").UseMutationResult Promise; +}, "data">, unknown, AirdropNFTParams, unknown>; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| contract | Erc1155 | an instance of a | + +Returns: + +import("@tanstack/react-query").UseMutationResult<Omit<{ receipt: import("@ethersproject/abstract-provider").TransactionReceipt; data: () => Promise<unknown>; }, "data">, unknown, [AirdropNFTParams](./react.airdropnftparams.md), unknown> + +a mutation object that can be used to transfer batch NFTs + +## Example 1 + + +```jsx +const Component = () => { + const editionDrop = useEditionDrop(); + const { + mutate: airdropNFT, + isLoading, + error, + } = useAirdropNFT(editionDrop); + + if (error) { + console.error("failed to transfer batch NFTs", error); + } + + return ( + +}; +``` + +## Example 2 + + +```jsx +const Component = () => { + const { contract } = useContract(); + const { + mutate: airdropNFT, + isLoading, + error, + } = useAirdropNFT(contract?.nft); + + if (error) { + console.error("failed to transfer batch NFTs", error); + } + + return ( + + ); +}; +``` + diff --git a/docs/react.usetransfernft.md b/docs/react.usetransfernft.md new file mode 100644 index 0000000..2984c22 --- /dev/null +++ b/docs/react.usetransfernft.md @@ -0,0 +1,86 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [useTransferNFT](./react.usetransfernft.md) + +## useTransferNFT() function + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Use this to transfer tokens on your [NFTContract](./react.nftcontract.md) + +Signature: + +```typescript +export declare function useTransferNFT(contract: RequiredParam): import("@tanstack/react-query").UseMutationResult Promise; +}, "data">, unknown, TransferNFTParams, unknown>; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| contract | [RequiredParam](./react.requiredparam.md)<TContract> | an instance of a [NFTContract](./react.nftcontract.md) | + +Returns: + +import("@tanstack/react-query").UseMutationResult<Omit<{ receipt: import("@ethersproject/abstract-provider").TransactionReceipt; data: () => Promise<unknown>; }, "data">, unknown, [TransferNFTParams](./react.transfernftparams.md)<TContract>, unknown> + +a mutation object that can be used to transfer NFTs + +## Example 1 + + +```jsx +const Component = () => { + const nftDrop = useNFTDrop(); + const { + mutate: transferNFT, + isLoading, + error, + } = useTransferNFT(nftDrop); + + if (error) { + console.error("failed to transfer nft", error); + } + + return ( + + ); +}; +``` + +## Example 2 + + +```jsx +const Component = () => { + const { contract } = useContract(); + const { + mutate: transferNFT, + isLoading, + error, + } = useTransferNFT(contract?.nft); + + if (error) { + console.error("failed to transfer nft", error); + } + + return ( + + ); +}; +``` + diff --git a/etc/react.api.md b/etc/react.api.md index 7ec1b32..334448c 100644 --- a/etc/react.api.md +++ b/etc/react.api.md @@ -5,6 +5,7 @@ ```ts import { AbiFunction } from '@thirdweb-dev/sdk/dist/browser'; +import type { AirdropInput } from '@thirdweb-dev/sdk/dist/browser'; import type { Amount } from '@thirdweb-dev/sdk/dist/browser'; import { AuctionListing } from '@thirdweb-dev/sdk/dist/browser'; import { BaseContract } from 'ethers'; @@ -81,6 +82,12 @@ import type { ValidContractInstance } from '@thirdweb-dev/sdk/dist/browser'; import { Vote } from '@thirdweb-dev/sdk/dist/browser'; import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'; +// @beta +export type AirdropNFTParams = { + tokenId: BigNumberish; + addresses: AirdropInput; +}; + // @public (undocumented) export type BuyNowParams = TListingType extends ListingType.Direct ? { id: BigNumberish; @@ -295,7 +302,17 @@ export interface ThirdwebSDKProviderProps extends Pick = TContract extends Erc1155 ? { + to: WalletAddress; + tokenId: BigNumberish; + amount: Amount; +} : { + to: WalletAddress; + tokenId: BigNumberish; }; export { useAccount } @@ -337,6 +354,12 @@ export function useActiveListings(contract: RequiredParam, filter?: // @public export function useAddress(): string | undefined; +// @beta +export function useAirdropNFT(contract: Erc1155): UseMutationResult Promise; +}, "data">, unknown, AirdropNFTParams, unknown>; + // @beta export function useAllContractEvents(contract: RequiredParam["contract"]>, options?: { queryFilter?: EventQueryFilter; @@ -1574,6 +1597,12 @@ export function useTotalCount(contract: RequiredParam): UseQueryRes // @beta export function useTransferBatchToken(contract: RequiredParam): UseMutationResult; +// @beta +export function useTransferNFT(contract: RequiredParam): UseMutationResult Promise; +}, "data">, unknown, TransferNFTParams, unknown>; + // @beta export function useTransferToken(contract: RequiredParam): UseMutationResult( }, ); } + +/** + * Use this to transfer tokens on your {@link NFTContract} + * + * @example + * ```jsx + * const Component = () => { + * const nftDrop = useNFTDrop(); + * const { + * mutate: transferNFT, + * isLoading, + * error, + * } = useTransferNFT(nftDrop); + * + * if (error) { + * console.error("failed to transfer nft", error); + * } + * + * return ( + * + * ); + * }; + * ``` + * @example + * ```jsx + * const Component = () => { + * const { contract } = useContract(); + * const { + * mutate: transferNFT, + * isLoading, + * error, + * } = useTransferNFT(contract?.nft); + * + * if (error) { + * console.error("failed to transfer nft", error); + * } + * + * return ( + * + * ); + * }; + * ``` + * + * @param contract - an instance of a {@link NFTContract} + * @returns a mutation object that can be used to transfer NFTs + * @beta + */ +export function useTransferNFT( + contract: RequiredParam, +) { + const activeChainId = useActiveChainId(); + const contractAddress = contract?.getAddress(); + const queryClient = useQueryClient(); + + return useMutation( + (data: TransferNFTParams) => { + invariant(contract?.transfer, "contract does not support transfer"); + if (contract instanceof Erc1155) { + invariant("amount" in data, "amount not provided"); + return contract.transfer(data.to, data.tokenId, data.amount); + } + + return contract.transfer(data.to, data.tokenId); + }, + { + onSettled: () => + invalidateContractAndBalances( + queryClient, + contractAddress, + activeChainId, + ), + }, + ); +} + +/** + * Use this to transfer tokens on your {@link Erc1155} + * + * @example + * ```jsx + * const Component = () => { + * const editionDrop = useEditionDrop(); + * const { + * mutate: airdropNFT, + * isLoading, + * error, + * } = useAirdropNFT(editionDrop); + * + * if (error) { + * console.error("failed to transfer batch NFTs", error); + * } + * + * return ( + * + * }; + * ``` + * @example + * ```jsx + * const Component = () => { + * const { contract } = useContract(); + * const { + * mutate: airdropNFT, + * isLoading, + * error, + * } = useAirdropNFT(contract?.nft); + * + * if (error) { + * console.error("failed to transfer batch NFTs", error); + * } + * + * return ( + * + * ); + * }; + * ``` + * + * @param contract - an instance of a {@link Erc1155} + * @returns a mutation object that can be used to transfer batch NFTs + * @beta + */ +export function useAirdropNFT(contract: Erc1155) { + const activeChainId = useActiveChainId(); + const contractAddress = contract?.getAddress(); + const queryClient = useQueryClient(); + + return useMutation( + ({ tokenId, addresses }: AirdropNFTParams) => { + invariant(contract?.airdrop, "contract does not support airdrop"); + + return contract.airdrop(tokenId, addresses); + }, + { + onSettled: () => + invalidateContractAndBalances( + queryClient, + contractAddress, + activeChainId, + ), + }, + ); +} diff --git a/src/types.ts b/src/types.ts index 79f3e44..c9c5b9e 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,4 +1,5 @@ import type { + AirdropInput, Amount, EditionDrop, Erc721, @@ -40,7 +41,7 @@ export type ContractAddress = string; */ export type TokenParams = { to: WalletAddress; - amount: string | number; + amount: Amount; }; // NFTS // @@ -121,6 +122,23 @@ export type useNFTBalanceParams = TContract extends Erc1155 ownerWalletAddress: RequiredParam, ]; +/** + * The params to pass to `useTransferNFT`. + * @beta + */ +export type TransferNFTParams = TContract extends Erc1155 + ? { to: WalletAddress; tokenId: BigNumberish; amount: Amount } + : { to: WalletAddress; tokenId: BigNumberish }; + +/** + * The params to pass to `useTransferBatchNFT`. + * @beta + */ +export type AirdropNFTParams = { + tokenId: BigNumberish; + addresses: AirdropInput; +}; + /** * The params for the {@link useMintNFT} hook mutation. *