diff --git a/README.md b/README.md index cda1d0c..1bd7f60 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,10 @@ -This package includes all sorts of tooling for the Hedera NFT ecosystem, including: +This package includes all sorts of tooling for the Hedera NFT ecosystem. Some additional features are available only in Node.js e.g: **Local token metadata validator**. -1. **Local token metadata validator:** Verify your metadata locally against the [token metadata schema](https://docs.hedera.com/hedera/tutorials/token/structure-your-token-metadata-using-json-schema-v2) for NFTs, which returns errors and warnings against the standard. You can also define your own token metadata standard and add it to the package to use this schema for validation. -2. **Local metadata validator:** Verify a local folder containing multiple JSON metadata files against the token metadata schema before publishing the NFT collection on the Hedera network. +1. **Token metadata validator** Verify your metadata against the [token metadata schema](https://docs.hedera.com/hedera/tutorials/token/structure-your-token-metadata-using-json-schema-v2) for NFTs, which returns errors and warnings against the standard. You can also define your own token metadata standard and add it to the package to use this schema for validation. +2. **Local metadata validator - available in Node.js:** Verify a local folder containing multiple JSON metadata files against the token metadata schema before publishing the NFT collection on the Hedera network. 3. **Risk score calculation:** Calculate a risk score for an NFT collection from the token information or by passing a token ID of an NFT on the Hedera testnet or mainnet. 4. **Rarity score calculation:** Calculate the rarity scores for a local folder containing multiple JSON metadata files for an NFT collection. 5. **Trait occurrence calculation:** Calculate how often different values for a given trait occur in a collection, percentage-based. @@ -18,10 +18,10 @@ This package includes all sorts of tooling for the Hedera NFT ecosystem, includi 8. **Metadata Validator:** A tool for validating metadata objects according to [token metadata schema](https://docs.hedera.com/hedera/tutorials/token/structure-your-token-metadata-using-json-schema-v2), providing comprehensive verification of metadata compliance with the selected standard. 9. **Metadata Builder:** Enables the creation and assembly of NFT metadata objects in a structured format and conducts instant validation within its build method, ensuring adherence to [token metadata schema](https://docs.hedera.com/hedera/tutorials/token/structure-your-token-metadata-using-json-schema-v2) prior to deployment. 10. **Convert CSV To Metadata Objects:** Facilitates the conversion of CSV file data into structured metadata objects, streamlining the initial stages of NFT metadata preparation. -11. **Convert Metadata Objects to JSON Files:** Transforms validated metadata objects into JSON files, ensuring that NFT metadata is properly formatted and stored for deployment. +11. **Convert Metadata Objects to JSON Files - available in Node.js:** Transforms validated metadata objects into JSON files, ensuring that NFT metadata is properly formatted and stored for deployment. 12. **Prepare Metadata Objects From CSV Rows:** Processes rows of CSV data into ready to validate metadata objects, bridging the gap between raw data collection and NFT metadata standardization. 13. **Upload Service:** Provides tools for uploading files to your chosen file storage service, including: - - **uploadFilesFromPath:** Uploads all files from given directory paths or specific files to the configured storage service and returns URLs to the uploaded files. + - **uploadFilesFromPath - available in Node.js:** Uploads all files from given directory paths or specific files to the configured storage service and returns URLs to the uploaded files. - **uploadBlobFiles:** Handles the upload of blob files or buffer files and returns URLs to these files, ensuring that files are not empty before upload. - **handleBlobUpload:** Specifically designed for uploading NFT metadata as JSON blobs, generating a URL where the metadata is stored. - **uploadMetadataList:** Allows for batch uploading of NFT metadata, handling each metadata item individually and compiling the resulting URLs. @@ -34,8 +34,8 @@ This package includes all sorts of tooling for the Hedera NFT ecosystem, includi ## Table of Contents - **How to build the package** -- **Package: [Local token metadata validator](#local-token-metadata-validator)** -- **Package: [Local metadata validator](#local-validator)** +- **Package: [Token metadata validator](#local-token-metadata-validator)** +- **Package: [Local metadata validator - available in Node.js](#local-validator)** - **Package: [Risk score calculation](#risk-score-calculation)** - **Package: [Rarity score calculation](#rarity-score-calculation)** - **Package: [Trait occurrence calculation](#trait-occurrence-calculation)** @@ -44,9 +44,9 @@ This package includes all sorts of tooling for the Hedera NFT ecosystem, includi - **Package: [Metadata Validator](#metadata-validator)** - **Package: [Metadata Builder](#metadata-builder)** - **Package: [Convert CSV To Metadata Objects](#convert-csv-to-metadata-objects)** -- **Package: [Convert Metadata Objects to JSON Files](#convert-metadata-objects-to-json-files)** +- **Package: [Convert Metadata Objects to JSON Files - available in Node.js](#convert-metadata-objects-to-json-files)** - **Package: [Prepare Metadata Objects From CSV Rows](#prepare-metadata-objects-from-csv-rows)** -- **Package: [Upload Service](#upload-service)** +- **Package: [Upload Service - with Node.js features](#upload-service)** - **Package: [File Storage Services](#file-storage-services)** - **[Changes in browser bundle](#changes-in-browser-bundle)** - **[Questions, contact us, or improvement proposals?](#questions-or-improvement-proposals)** @@ -445,17 +445,32 @@ Install the package: npm i -s @hashgraph/hedera-nft-sdk ``` -Import the package into your project and get `calculateRarity` function. Next, you need to pass a relative path to a folder containing metadata JSON files. +Import the package into your project and get `calculateRarity` function. Next, you need to pass an array of your metadata files: + +```js + [ + { + fileName: '1.json', + file: new Blob[JSON.stringify("{ name: 'Nft name', ...} "), { type: 'application/json'}] + } + ] +``` ```js const { calculateRarity } = require('@hashgraph/hedera-nft-sdk'); -const relativePathToFiles = './examples/local-metadata-validator/files'; -const results = calculateRarity(relativePathToFiles); +const metadataFiles = [ + { + fileName: '1.json', + file: new Blob[JSON.stringify("{ name: 'Nft name', ...}"), { type: 'application/json' }] + } +] + +const results = await calculateRarity(metadataFiles); console.log(results); ``` -You can also avoid having to load data from files by using the `calculateRarityFromData` function. +You can also avoid having to load data with Blob interface and instead use `calculateRarityFromData` function. ```js const NFTdata = [ @@ -543,7 +558,6 @@ Here's a sample output. The total sum of the individual attributes is always 100 See: -- **[/examples/rarity-score-calculation/rarity-from-files.js](https://github.com/hashgraph/hedera-nft-sdk/tree/main/examples/rarity-score-calculation)** - **[/examples/rarity-score-calculation/rarity-from-data.js](https://github.com/hashgraph/hedera-nft-sdk/tree/main/examples/rarity-score-calculation)** ## Trait occurrence calculation @@ -1506,16 +1520,20 @@ The `convertCSVToMetadataObjects` function is designed to transform CSV files in ### Usage -To convert a CSV file into an array of metadata objects, you need to provide the path to the CSV file. Optionally, you can also specify a limit to control the number of rows processed from the CSV file. +To convert a CSV file into an array of metadata objects, you need to provide the CSV file. Optionally, you can also specify a limit to control the number of rows processed from the CSV file. ```ts -const csvFilePath = 'path/to/your/csv-file.csv'; -const metadataObjects = await convertCSVToMetadataObjects(csvFilePath, 100); +function convertCSV(csvFile: File) { + const metadataObjects = await convertCSVToMetadataObjects(csvFile, 100); +} +// or +const csvBlob = new Blob(['csv string'], { type: 'text/csv' }) +const metadataObjects = await convertCSVToMetadataObjects(csvBlob, 100); ``` ### Parameters -- `csvFilePath`: A string that specifies the path to the CSV file containing the NFT metadata information, +- `csvFile`: instance that fulfils Blob interface, - `limit`: An optional parameter that defines the maximum number of rows to be processed from the CSV file. If not provided, all rows in the file will be processed. Important! The first two lines in the csv file are headers and they are skipped. You can find a valid csv example at the path `src/test/__mocks__/csv/csv-example-with-all-fields` @@ -1530,7 +1548,7 @@ If the CSV file contains fewer data rows than the headers (after omitting specif --- -## Convert Metadata Objects to JSON Files +## Convert Metadata Objects to JSON Files - available in Node.js The `convertMetadataObjectsToJsonFiles` function streamlines the process of converting an array of NFT metadata objects into individual JSON files. This utility is particularly useful for batch processing and storage of NFT metadata, facilitating easy upload and management of NFT collections. Before conversion, it validates each metadata object against the token metadata schema to ensure compliance. @@ -1613,7 +1631,7 @@ The Upload Service class is a versatile component of the SDK that facilitates th The class methods offer diverse functionalities to upload files from paths, blob objects, buffer files, and NFT metadata, catering to different needs of the NFT ecosystem. -1. `uploadFilesFromPath` - Uploads files from given directory paths or specific file paths to the configured storage service and returns URLs to the uploaded files. +1. `uploadFilesFromPath` - available in Node.js - Uploads files from given directory paths or specific file paths to the configured storage service and returns URLs to the uploaded files. ### Usage @@ -1654,7 +1672,7 @@ This method returns an array of objects, each detailing the content of the uploa ```ts type UploadServiceReturn = { - content: Blob | BufferFile; + content: Blob; url: string; }[]; ``` @@ -1690,8 +1708,8 @@ type UploadServiceReturn = { ### Usage ```ts -const metadatas = [{ name: 'NFT 1' }, { name: 'NFT 2' }]; -const metadataListUploadResults = await uploadService.uploadMetadataList(metadatas); +const metadata = [{ name: 'NFT 1' }, { name: 'NFT 2' }]; +const metadataListUploadResults = await uploadService.uploadMetadataList(metadata); ``` ### Output @@ -1810,26 +1828,12 @@ type UploadResult = { ``` --- -## Changes in browser bundle - -1. **Removal of [Convert CSV To Metadata Objects](#convert-csv-to-metadata-objects)**: - - Removed the `convertCSVToMetadataObjects` function. This function directly accesses files from the user's file system, which is not supported in a browser environment. - -2. **Updates in Package [NFT SDK Methods](#nft-sdk-methods)**: - - **Functions `estimateCreateCollectionInDollars` and `estimateCreateCollectionInHbar`:** Both functions use the `get-string-size` module, which relies on `Blob` (a factory for `Buffer` not accessible in browsers) to calculate byte string sizes. - - **Function: `mintUniqueMetadataFunction`**: This function allows passing a file path for metadata URIs, which is not feasible in a browser environment. Browsers cannot access the local file system. - -3. **Updates in Package [Upload Service](#upload-service)**: - - **Function: `uploadFilesFromPath`**: This method uses the `fs` library to upload files from the disk, which is not supported in a browser environment. Browsers cannot access the local file system. - -4. **Updates in Package [Convert Metadata Objects to JSON Files](#convert-metadata-objects-to-json-files)**: - - **Function: `convertMetadataObjectsToJsonFiles`**: This function attempts to save files to the file system, which is not possible in a browser environment. Browsers cannot access the local file system. - -5. **Updates in Package [Local metadata validator](#local-validator)**: - - **Local metadata validator**: The `Local metadata validator` method relies on the `fs` and `path` packages to read JSON files from the disk, which is unsupported in browsers. +## Node.js features in browser bundle: + - **Local metadata validator** + - **Convert Metadata Objects to JSON Files** + - **Upload Service - uploadFilesFromPath** -6. **Updates in Package [Rarity score calculation](#rarity-score-calculation)**: - - **Function: `calculateRarity`**: The `calculateRarity` (from JSON files) method relies on the `fs` and `path` packages to read JSON files from the disk, which is unsupported in browsers. This particular method is not supported in browser. +Listed features utilized in browser environment will throw an error. ## Build diff --git a/examples/rarity-score-calculation/rarity-from-files.js b/examples/rarity-score-calculation/rarity-from-files.js deleted file mode 100644 index e9dd949..0000000 --- a/examples/rarity-score-calculation/rarity-from-files.js +++ /dev/null @@ -1,129 +0,0 @@ -/*- - * - * Hedera NFT SDK - * - * Copyright (C) 2023 Hedera Hashgraph, LLC - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - */ -const { calculateRarity } = require('../../dist'); -const { Parser } = require('json2csv'); -const fs = require('fs'); - -function main() { - // Replace with absolute path to files folder - const relativePathToFiles = './examples/local-metadata-validator/files'; - const results = calculateRarity(relativePathToFiles); - console.log(JSON.stringify(results, null, 4)); - - let flatData = results.reduce((arr, row) => { - row.attributeContributions.forEach((contribution) => { - let newRow = { - NFT: row.NFT, - filename: row.filename, - totalRarity: row.totalRarity, - trait: contribution.trait, - value: contribution.value, - contribution: contribution.contribution, - }; - arr.push(newRow); - }); - return arr; - }, []); - - const fields = ['NFT', 'filename', 'totalRarity', 'trait', 'value', 'contribution']; - const opts = { fields }; - - try { - const parser = new Parser(opts); - const csv = parser.parse(flatData); - - fs.writeFile('output.csv', csv, function (err) { - if (err) throw err; - console.log('\nFile saved as output.csv'); - }); - } catch (err) { - console.error(err); - } - - /* Output: - Found 6 for directory: /Users/myUser/hedera-nft-sdk/examples/rarity-score-calculation/files - Found 5 files with the .json extension - [ - { - attributeContributions: [ - { trait: "Background", value: "Yellow", contribution: "18.18" }, - { trait: "Fur", value: "Gold", contribution: "18.18" }, - { trait: "Clothing", value: "Floral Jacket", contribution: "18.18" }, - { trait: "Mouth", value: "Tongue", contribution: "27.27" }, - { trait: "Sing", value: "None", contribution: "18.18" }, - ], - totalRarity: "5.50", - NFT: 1, - filename: "nft1.json", - }, - { - attributeContributions: [ - { trait: "Background", value: "Green", contribution: "25.00" }, - { trait: "Fur", value: "Gold", contribution: "16.67" }, - { trait: "Clothing", value: "Floral Jacket", contribution: "16.67" }, - { trait: "Mouth", value: "Tongue", contribution: "25.00" }, - { trait: "Sing", value: "None", contribution: "16.67" }, - ], - totalRarity: "6.00", - NFT: 2, - filename: "nft2.json", - }, - { - attributeContributions: [ - { trait: "Background", value: "Yellow", contribution: "18.18" }, - { trait: "Fur", value: "Silver", contribution: "27.27" }, - { trait: "Clothing", value: "Floral Jacket", contribution: "18.18" }, - { trait: "Mouth", value: "Smile", contribution: "18.18" }, - { trait: "Sing", value: "None", contribution: "18.18" }, - ], - totalRarity: "5.50", - NFT: 3, - filename: "nft3.json", - }, - { - attributeContributions: [ - { trait: "Background", value: "Green", contribution: "27.27" }, - { trait: "Fur", value: "Gold", contribution: "18.18" }, - { trait: "Clothing", value: "Floral Jacket", contribution: "18.18" }, - { trait: "Mouth", value: "Smile", contribution: "18.18" }, - { trait: "Sing", value: "None", contribution: "18.18" }, - ], - totalRarity: "5.50", - NFT: 4, - filename: "nft4.json", - }, - { - attributeContributions: [ - { trait: "Background", value: "Yellow", contribution: "8.70" }, - { trait: "Fur", value: "Silver", contribution: "13.04" }, - { trait: "Clothing", value: "Herbal Jacket", contribution: "34.78" }, - { trait: "Mouth", value: "Smile", contribution: "8.70" }, - { trait: "Sing", value: "Sing", contribution: "34.78" }, - ], - totalRarity: "11.50", - NFT: 5, - filename: "nft5.json", - } - ] - File saved as output.csv - */ -} - -main(); diff --git a/src/browser.ts b/src/browser.ts index f2ba6d5..1ef2163 100644 --- a/src/browser.ts +++ b/src/browser.ts @@ -65,11 +65,7 @@ export { convertCSVToMetadataObjects } from './file-management/convert-csv-to-me * Function below is not browser supported * @browserUnsupported */ -// export { convertCSVToMetadataObjects } from './file-management/convert-csv-to-metadata-objects'; -/** - * Function below is not browser supported - * @browserUnsupported -*/ +export { convertMetadataObjectsToJsonFiles } from './file-management/convert-metadata-objects-to-json-files.browser'; export { prepareMetadataObjectsFromCSVRows } from './file-management/prepare-metadata-objects-from-csv-rows'; export { getHolderAndDuration } from './get-holder-and-duration'; diff --git a/src/file-management/convert-metadata-objects-to-json-files.browser.ts b/src/file-management/convert-metadata-objects-to-json-files.browser.ts new file mode 100644 index 0000000..5ef2cfa --- /dev/null +++ b/src/file-management/convert-metadata-objects-to-json-files.browser.ts @@ -0,0 +1,30 @@ +/*- + * + * Hedera NFT SDK + * + * Copyright (C) 2024 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ +import { JsonMetadataFromCSVInterface } from '../types/json-metadata-from-csv'; +import { MetadataObject } from '../types/csv'; +import { dictionary } from '../utils/constants/dictionary'; + +export const convertMetadataObjectsToJsonFiles = async (_: { + metadataObjects: MetadataObject[]; + savedJsonFilesLocation: string; + limit?: number; +}): Promise => { + throw new Error(dictionary.errors.nodeFeature) +}; diff --git a/src/helpers/files.browser.ts b/src/helpers/files.browser.ts index 857eccc..3649324 100644 --- a/src/helpers/files.browser.ts +++ b/src/helpers/files.browser.ts @@ -18,6 +18,7 @@ * */ import { Instance } from '../types/validator'; +import { dictionary } from '../utils/constants/dictionary'; /** * Function below is not browser supported @@ -41,5 +42,5 @@ export const readFiles = (_: string, __: string[]): { filename: string; filedata * @returns An array of filenames with extension */ export const getJSONFilesForPath = (_: string): string[] => { - throw new Error('Not supported in browser.'); + throw new Error(dictionary.errors.nodeFeature); }; diff --git a/src/helpers/save-metadata-object-as-json-files.browser.ts b/src/helpers/save-metadata-object-as-json-files.browser.ts index 4163ae3..b238942 100644 --- a/src/helpers/save-metadata-object-as-json-files.browser.ts +++ b/src/helpers/save-metadata-object-as-json-files.browser.ts @@ -18,7 +18,8 @@ * */ import { MetadataObject } from '../types/csv'; +import { dictionary } from '../utils/constants/dictionary'; export const saveMetadataObjectsAsJsonFiles = (_: MetadataObject[], __: string): void => { - throw new Error('Not supported in browser.') + throw new Error(dictionary.errors.nodeFeature) }; diff --git a/src/local-validation/browser.ts b/src/local-validation/browser.ts index 61b0b2c..65019fb 100644 --- a/src/local-validation/browser.ts +++ b/src/local-validation/browser.ts @@ -18,6 +18,7 @@ * */ import { ValidationResult } from '../types/validator'; +import { dictionary } from '../utils/constants/dictionary'; interface ValidationResults { [key: string]: ValidationResult; @@ -33,7 +34,7 @@ interface ValidationResults { * @returns {Object, validationResults>} */ const localValidation = (_: string): ValidationResults => { - throw new Error('Not supported in browser.') + throw new Error(dictionary.errors.nodeFeature) }; export { diff --git a/src/services/upload-service.browser.ts b/src/services/upload-service.browser.ts index 5893c6d..567aef1 100644 --- a/src/services/upload-service.browser.ts +++ b/src/services/upload-service.browser.ts @@ -46,7 +46,7 @@ export class UploadService { * @browserUnsupported */ public async uploadFilesFromPath(_: string[]): Promise { - throw new Error('Not supported in browser.'); + throw new Error(dictionary.errors.nodeFeature); } public async uploadBlobFiles(files: Blob[]): Promise { diff --git a/src/utils/constants/dictionary.ts b/src/utils/constants/dictionary.ts index 3c1881b..fb74cfa 100644 --- a/src/utils/constants/dictionary.ts +++ b/src/utils/constants/dictionary.ts @@ -21,6 +21,7 @@ import { getFullSystemPath } from '../../helpers/get-full-system-path'; export const dictionary = { errors: { + nodeFeature: 'Feature available in Node.js', nftDeleted: 'NFT has been deleted.', nftNoTransactions: 'NFT has not any transactions yet', privateKeyRequired: 'Private key is required',