Skip to content
This repository was archived by the owner on Oct 19, 2023. It is now read-only.

Commit 725872e

Browse files
spielcryptospielcrypto
committed
add tsdocs to nevermined.tsx
1 parent f2cf8b6 commit 725872e

File tree

4 files changed

+270
-7
lines changed

4 files changed

+270
-7
lines changed

‎example/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
]
3333
},
3434
"dependencies": {
35-
"@nevermined-io/catalog-core": "0.0.24",
35+
"@nevermined-io/catalog-core": "0.0.25",
3636
"@nevermined-io/catalog-providers": "0.0.22",
3737
"@nevermined-io/nevermined-sdk-js": "^0.22.5",
3838
"axios": "^0.24.0",

‎lib/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@nevermined-io/catalog-core",
3-
"version": "0.0.24",
3+
"version": "0.0.25",
44
"private": false,
55
"scripts": {
66
"watch": "./node_modules/.bin/nodemon",

‎lib/src/nevermined.tsx‎

Lines changed: 267 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
183183
};
184184

185185
/**
186-
* `account` contain all the functionalities to handle authentications and
186+
* `account` contains all the functionalities to handle authentications and
187187
* collections belonged to an account
188188
*
189189
* @example
@@ -340,8 +340,102 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
340340
};
341341

342342
/**
343-
* `assets` contain all the functionalities to handle assets for example get,
343+
* `assets` contains all the functionalities to handle assets for example get,
344344
* mint, transfer, order or download asset asset
345+
*
346+
* @example
347+
* Mint an asset example:
348+
*
349+
* ```
350+
* const Example = () => {
351+
* const { isLoadingSDK, sdk, account, assets } = Catalog.useNevermined();
352+
* const [ddo, setDDO] = useState<DDO>({} as DDO)
353+
*
354+
* const metadata: MetaData = {
355+
* main: {
356+
* name: '',
357+
* files: [{
358+
* index: 0,
359+
* contentType: 'application/json',
360+
* url: 'https://github.com/nevermined-io/docs/blob/master/docs/architecture/specs/metadata/examples/ddo-example.json'
361+
* }],
362+
* type: 'dataset',
363+
* author: '',
364+
* license: '',
365+
* dateCreated: new Date().toISOString(),
366+
* price: ''
367+
* }
368+
* };
369+
*
370+
* const constructRewardMap = (
371+
* recipientsData: any[],
372+
* priceWithoutFee: number,
373+
* ownerWalletAddress: string
374+
* ): Map<string, BigNumber> => {
375+
* const rewardMap: Map<string, BigNumber> = new Map();
376+
* let recipients: any = [];
377+
* if (recipientsData.length === 1 && recipientsData[0].split === 0) {
378+
* recipients = [
379+
* {
380+
* name: ownerWalletAddress,
381+
* split: 100,
382+
* walletAddress: ownerWalletAddress
383+
* }
384+
* ];
385+
* }
386+
* let totalWithoutUser = 0;
387+
*
388+
* recipients.forEach((recipient: any) => {
389+
* if (recipient.split && recipient.split > 0) {
390+
* const ownSplit = ((priceWithoutFee * recipient.split) / 100).toFixed();
391+
* rewardMap.set(recipient.walletAddress, BigNumber.from(+ownSplit));
392+
* totalWithoutUser += recipient.split;
393+
* }
394+
* });
395+
*
396+
* if (!rewardMap.has(ownerWalletAddress)) {
397+
* const ownSplitReinforced = +((priceWithoutFee * (100 - totalWithoutUser)) / 100).toFixed();
398+
* rewardMap.set(ownerWalletAddress, BigNumber.from(ownSplitReinforced));
399+
* }
400+
*
401+
* return rewardMap;
402+
* };
403+
*
404+
* const mint = async () => {
405+
* try {
406+
* const publisher = await getCurrentAccount(sdk);
407+
* const rewardsRecipients: any[] = [];
408+
* const assetRewardsMap = constructRewardMap(rewardsRecipients, 100, publisher.getId());
409+
* const assetRewards = new AssetRewards(assetRewardsMap);
410+
* const data: MintNFTInput = {
411+
* metadata,
412+
* publisher,
413+
* cap: 100,
414+
* royalties: 0,
415+
* nftAmount: 1,
416+
* preMint: true,
417+
* erc20TokenAddress: '0x2058A9D7613eEE744279e3856Ef0eAda5FCbaA7e', //usdc token
418+
* //@ts-ignore
419+
* assetRewards
420+
* };
421+
* if (!account.isTokenValid()) {
422+
* await account.generateToken();
423+
* }
424+
* const response = await assets.mint(data);
425+
* setDDO(response);
426+
* } catch (error) {
427+
* console.log('error', error);
428+
* }
429+
* };
430+
*
431+
* return (
432+
* <>
433+
* ...
434+
* </>
435+
* );
436+
* };
437+
* ```
438+
*
345439
*/
346440
const assets: AssetsModule = {
347441
getSingle: async (did: string): Promise<DDO> => {
@@ -374,7 +468,7 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
374468
/**
375469
* Mint an asset
376470
* @param input Object input with all the data required to mint an asset
377-
* @returns If the asset was minted successfuly the function will return `true`
471+
* @returns If the asset was minted successfully the function will return `true`
378472
*/
379473
mint: async (input: MintNFTInput): Promise<DDO | undefined> => {
380474
try {
@@ -424,7 +518,7 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
424518
* @param assetInfo
425519
* @param assetInfo.did The id of the asset
426520
* @param assetInfo.amount The amount of asset to transfer
427-
* @returns Return true if asset was transferred successfuly
521+
* @returns Return true if asset was transferred successfully
428522
*/
429523
transfer: async ({ did, amount }: { did: string; amount: number }): Promise<boolean> => {
430524
try {
@@ -490,6 +584,12 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
490584
}
491585
},
492586

587+
/**
588+
* This method order a asset to allow after transfer to the buyer (the method only order but not transfer)
589+
* @param did id of the asset
590+
* @returns In case the order is completed successfully it returns the agreementId
591+
* which is needed to transfer the asset to the buyer
592+
*/
493593
orderAsset: async (did: string): Promise<string> => {
494594
const account = await getCurrentAccount(sdk);
495595

@@ -517,6 +617,13 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
517617
return sdk.assets.order(did, 'access', account);
518618
},
519619

620+
/**
621+
* This method order a NFT1155 asset to allow after transfer to the buyer (the method only order but not transfer)
622+
* @param did id of the NFT1155 asset
623+
* @param amount Amount of NFT1155 assets to order
624+
* @returns In case the order is completed successfully it returns the agreementId
625+
* which is needed to transfer the NFT1155 asset to the buyer
626+
*/
520627
orderNFT1155: async (did: string, amount = 1): Promise<string> => {
521628
const account = await getCurrentAccount(sdk);
522629

@@ -529,6 +636,13 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
529636
return sdk.nfts.order(did, amount, account);
530637
},
531638

639+
/**
640+
* This method order a NFT721 asset to allow after transfer to the buyer (the method only order but not transfer)
641+
* @param did id of the NFT721 asset
642+
* @param amount Amount of NFT721 assets to order
643+
* @returns In case the order is completed successfully it returns the agreementId
644+
* which is needed to transfer the NFT721 asset to the buyer
645+
*/
532646
orderNFT721: async (did: string, nftTokenAddress: string): Promise<string> => {
533647
const account = await getCurrentAccount(sdk);
534648

@@ -541,6 +655,11 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
541655
return sdk.nfts.order721(did, account);
542656
},
543657

658+
/**
659+
* Get the aggreement details of the NFT asset (owner, nfts supplay, royalties, etc...)
660+
* @param did id of the NFT (721 & 1155) asset
661+
* @returns Agreement details of the NFT asset
662+
*/
544663
nftDetails: async (did: string): Promise<NFTDetails> => {
545664
try {
546665
if (isEmptyObject(sdk)) return {} as NFTDetails;
@@ -551,6 +670,12 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
551670
}
552671
},
553672

673+
/**
674+
* Download a NFT asset already ordered and transfered to the buyer,
675+
* if the user is the owner of the asset
676+
* @param did id of the NFT (721 & 1155) asset
677+
* @returns if the NFT is downloaded successfully the method will return a true
678+
*/
554679
downloadNFT: async (did: string): Promise<boolean> => {
555680
try {
556681
const account = await getCurrentAccount(sdk);
@@ -562,6 +687,12 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
562687
}
563688
},
564689

690+
/**
691+
* Download an asset already ordered and transfered to the buyer,
692+
* if the user is the owner of the asset
693+
* @param did id of the NFT (721 & 1155) asset
694+
* @returns if the NFT is downloaded successfully the method will return a true
695+
*/
565696
downloadAsset: async (did: string, agreementId: string): Promise<boolean> => {
566697
try {
567698
const account = await getCurrentAccount(sdk);
@@ -577,6 +708,11 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
577708
}
578709
},
579710

711+
/**
712+
* Get all the details about a custom erc20 token
713+
* @param customErc20TokenAddress The custom token address
714+
* @returns Custom token details
715+
*/
580716
getCustomErc20Token: async (customErc20TokenAddress: string) => {
581717
const customErc20Token = await sdk.contracts.loadErc20(customErc20TokenAddress);
582718
const account = await getCurrentAccount(sdk);
@@ -589,6 +725,12 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
589725
};
590726
},
591727

728+
/**
729+
* Upload files to Filecoin
730+
* @param file The file to upload to Filecoin
731+
* @param filecoinUrl The url of the Filecoin server
732+
* @returns The url where is located the file already uploaded
733+
*/
592734
uploadAssetToFilecoin: async (file: File, filecoinUrl: string) => {
593735
const form = new FormData();
594736
form.append('file', file);
@@ -601,7 +743,60 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
601743
}
602744
};
603745

746+
/**
747+
* `subscribe` contains all the functionalities to handle events
748+
*
749+
* @example
750+
* Subcribe payment event:
751+
*
752+
* ```
753+
* const Example = () => {
754+
* const { subscribe, subscription, account, isLoadingSDK} = Catalog.useNevermined();
755+
* const { paymentEvent, setPaymentEvent } = useState<ContractEventSubscription>();
756+
*
757+
* const buy = async () => {
758+
* if (!account.isTokenValid()) {
759+
* await account.generateToken();
760+
* }
761+
*
762+
* const currentAccount = await getCurrentAccount(sdk);
763+
* const response = await subscription.buySubscription(ddo.id, currentAccount, owner, 1, 1155);
764+
* };
765+
*
766+
* const stopLog = () => {
767+
* paymentEvent.unsuscribe();
768+
* }
769+
*
770+
* useEffect(() => {
771+
* if(isLoadingSDK) {
772+
* return;
773+
* }
774+
* (async () => {
775+
* setPaymentEvent(subscribe.paymentEvents((events)=> {
776+
* Logger.log(events)
777+
* }))
778+
* })()
779+
* }, [isLoadingSDK])
780+
*
781+
* return (
782+
* <div>
783+
* <button onClick={buy} disabled={isLoadingSDK}>
784+
* buy
785+
* </button>
786+
* <button onClick={stopLog} disabled={isLoadingSDK}>
787+
* Stop the logs
788+
* </button>
789+
* </div>
790+
* );
791+
* }
792+
* ```
793+
*/
604794
const subscribe: SubscribeModule = {
795+
/**
796+
* Subscribe a `payment` event and execute callbacks once that this event is listened
797+
* @param cb Callback event
798+
* @returns return the `payment` event with a functionality to unsubscribe
799+
*/
605800
paymentEvents: (cb: (events: EventResult[]) => void): ContractEventSubscription => {
606801
try {
607802
const config = {
@@ -622,6 +817,11 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
622817
}
623818
},
624819

820+
/**
821+
* Subscribe a `transfer` event and execute callbacks once that this event is listened
822+
* @param cb Callback to execute
823+
* @returns return the `transfer` event with a functionality to unsubscribe
824+
*/
625825
transferEvents: (cb: (events: EventResult[]) => void): ContractEventSubscription => {
626826
try {
627827
const config = {
@@ -643,7 +843,70 @@ export const NeverminedProvider = ({ children, config, verbose }: NeverminedProv
643843
}
644844
};
645845

846+
/**
847+
* `subscription` contains all the functionalities to handle asset subscritions by payment
848+
*
849+
* @example
850+
* Buy subscription example
851+
*
852+
* ```
853+
*
854+
* const BuyAsset = ({ddo}: {ddo: DDO}) => {
855+
* const { assets, account, isLoadingSDK, subscription, sdk } = Catalog.useNevermined();
856+
* const { walletAddress } = MetaMask.useWallet();
857+
* const [ownNFT1155, setOwnNFT1155] = useState(false);
858+
* const [isBought, setIsBought] = useState(false);
859+
* const [owner, setOwner] = useState('');
860+
*
861+
* useEffect(() => {
862+
* (async () => {
863+
* setOwnNFT1155(await account.isNFT1155Holder(ddo.id, walletAddress));
864+
* setOwner(await sdk.assets.owner(ddo.id))
865+
* })()
866+
* }, [walletAddress, isBought])
867+
*
868+
* const buy = async () => {
869+
* if (!account.isTokenValid()) {
870+
* await account.generateToken();
871+
* }
872+
*
873+
* const currentAccount = await getCurrentAccount(sdk);
874+
* const response = await subscription.buySubscription(ddo.id, currentAccount, owner, 1, 1155);
875+
* setIsBought(response);
876+
* };
877+
*
878+
* const download = async () => {
879+
* await assets.downloadNFT(ddo.id);
880+
* };
881+
*
882+
* return (
883+
* <div>
884+
* {ownNFT1155 ? (
885+
* <button onClick={download} disabled={isLoadingSDK}>
886+
* Download NFT
887+
* </button>
888+
* ) : (
889+
* owner !== walletAddress ?
890+
* <button onClick={buy} disabled={isLoadingSDK}>
891+
* buy
892+
* </button>
893+
* : <span>The owner cannot buy, please change the account to buy the NFT asset</span>
894+
* )}
895+
* </div>
896+
* );
897+
* }
898+
* ```
899+
*/
646900
const subscription = {
901+
/**
902+
* Order a NFT asset and transfer and delegate it to the subscription buyer
903+
* @param subscriptionDid Id of the NFT to subscribe
904+
* @param buyer The account who buy the subscription of the NFT asset
905+
* @param nftHolder The owner of the NFT asset
906+
* @param nftAmount The amount of NFT asset to buy
907+
* @param nftType NFT asset type which can be 721 or 1155
908+
* @returns It is true if the subscription was successfully completed
909+
*/
647910
buySubscription: async (subscriptionDid: string, buyer: Account, nftHolder: string, nftAmount: number, nftType: NftTypes): Promise<boolean> => {
648911
try {
649912
const agreementId = nftType === 721 ? await sdk.nfts.order721(subscriptionDid, buyer): await sdk.nfts.order(subscriptionDid, nftAmount, buyer);

0 commit comments

Comments
 (0)