@twin.org/nft-cli 0.0.1-next.3

package/docs/examples.md

@@ -0,0 +1,141 @@
+# @twin.org/nft-cli - Examples
+
+## Command Line Tool
+
+First install the tool with the following script.
+
+```shell
+npm install @twin.org/nft-cli
+```
+
+Running the tool with no commands will provide help for all the commands. By issuing the following command you should see the result.
+
+```shell
+twin-nft
+```
+
+Output
+
+```shell
+🌍 TWIN NFT v1.0.0
+
+Usage: twin-nft [command]
+
+Options:
+  -V, --version                             output the version number
+  --lang <lang>                             The language to display the output in. (default: "en")
+  --load-env [env...]                       Load the env files to initialise any environment variables.
+  -h, --help                                display help for command
+
+Commands:
+  mnemonic [options]      Create a mnemonic.
+  address [options]       Create bech32 addresses and keys from the seed.
+  faucet [options]        Request funds from the faucet.
+  nft-mint [options]      Mint an NFT.
+  nft-resolve [options]   Resolve an NFT.
+  nft-burn [options]      Burn an NFT.
+  nft-transfer [options]  Transfer an NFT.
+```
+
+You can get further details on the sub commands by using the help option for the individual commands.
+
+```shell
+twin-nft nft-mint --help
+```
+
+Output
+
+```shell
+🌍 TWIN NFT v1.0.0
+
+Usage: twin-nft nft-mint [options]
+
+Mint an NFT.
+
+Options:
+  --seed <seed>                      The seed for the issuer address in hex or base64 used to fund the minting, or start with ! to read environment variable.
+  --issuer <issuer>                  The bech32 address of the NFT issuer, or start with ! to read environment variable.
+  --tag <tag>                        The tag for the NFT.
+  --immutable-json <immutable-json>  A JSON file to read which includes the immutable data for the NFT.
+  --mutable-json <mutable-json>      A JSON file to read which includes the mutable data for the NFT.
+  --no-console                       Hides the output in the console.
+  --json <filename>                  Creates a JSON file containing the output.
+  --merge-json                       If the JSON file already exists merge the data instead of overwriting.
+  --env <filename>                   Creates an env file containing the output.
+  --merge-env                        If the env file already exists merge the data instead of overwriting.
+  --node <url>                       The url for the node endpoint, or an environment variable name containing the url. (default: "!NODE_URL")
+  --explorer <url>                   The url for the explorer endpoint, or an environment variable name containing the url. (default: "!EXPLORER_URL")
+  -h, --help                         display help for command
+```
+
+The commands `mnemonic`, `address` and `faucet` are described in more detail in the examples for `crypto-cli` and `wallet-cli`.
+
+## Command
+
+### nft-mint
+
+Use this command to mint a new NFT, the issuer address must have sufficient funds to store the NFT. The seed and the funds can be generated using the `mnemonic` and `faucet` commands.
+
+```shell
+# Generate a seed and mnemonic and store it in the env file
+twin-nft mnemonic --env wallet.env
+# Generate an address and store it in the env file
+twin-nft address --load-env wallet.env --hrp tst --seed !SEED --count 4 --env wallet.env --merge-env
+```
+
+To run this on the IOTA testnet you will need an env file with the following settings. Store the following config as config.env
+
+```shell
+NODE_URL="https://api.testnet.iotaledger.net"
+FAUCET_URL="https://faucet.testnet.iotaledger.net/api/enqueue"
+EXPLORER_URL="https://explorer.iota.org/iota-testnet/"
+```
+
+We also need to create a JSON file containing the immutable metadata for the NFT. The following JSON file follows the IRC27 standard for NFT data. Save this file as `immutable.json` to use in the following scripts.
+
+```json
+{
+  "standard": "IRC27",
+  "version": "v1.0",
+  "type": "video/mp4",
+  "uri": "https://ipfs.io/ipfs/QmPoYcVm9fx47YXNTkhpMEYSxCD3Bqh7PJYr7eo5YjLgiT",
+  "name": "Test NFT",
+  "collectionName": "Test Collection",
+  "issuerName": "Test Issuer",
+  "description": "This is a test NFT."
+}
+```
+
+To request some funds and mint the NFT you can issue the following commands:
+
+```shell
+# Fund the controller address from the faucet loading the config and wallet env files
+twin-nft faucet --load-env config.env wallet.env --address !ADDRESS_0_BECH32
+
+# Mint the NFT and store the id in the nft.env file
+twin-nft nft-mint --load-env config.env wallet.env --seed !SEED --issuer !ADDRESS_0_BECH32 --tag MY-NFT --immutable-json immutable.json --env nft.env
+```
+
+### nft-resolve
+
+To resolve the NFT and retrieve its details issue the following command.
+
+```shell
+twin-nft nft-resolve --load-env config.env nft.env --id !NFT_ID
+```
+
+### nft-transfer
+
+You can transfer the NFT to another address using the following command. You must provide the seed from the current issuer/owner so that it can be unlocked and transferred. In this example we read the nft id from the env file and transfer to the second address we created earlier.
+
+```shell
+twin-nft nft-transfer --load-env config.env wallet.env nft.env --seed !SEED --id !NFT_ID --recipient !ADDRESS_1_BECH32
+```
+
+### nft-burn
+
+To burn the NFT and reclaim the funds we issue the following command. We still require the seed as we need to transfer the deposit funds back to the issuer/owner.
+
+```shell
+twin-nft nft-burn --load-env config.env wallet.env nft.env --seed !SEED --issuer !ADDRESS_1_BECH32 --id !NFT_ID
+```

package/docs/reference/classes/CLI.md

@@ -0,0 +1,45 @@
+# Class: CLI
+
+The main entry point for the CLI.
+
+## Extends
+
+- `CLIBase`
+
+## Constructors
+
+### new CLI()
+
+> **new CLI**(): [`CLI`](CLI.md)
+
+#### Returns
+
+[`CLI`](CLI.md)
+
+#### Inherited from
+
+`CLIBase.constructor`
+
+## Methods
+
+### run()
+
+> **run**(`argv`, `localesDirectory`?): `Promise`\<`number`\>
+
+Run the app.
+
+#### Parameters
+
+• **argv**: `string`[]
+
+The process arguments.
+
+• **localesDirectory?**: `string`
+
+The directory for the locales, default to relative to the script.
+
+#### Returns
+
+`Promise`\<`number`\>
+
+The exit code.

package/docs/reference/functions/actionCommandNftBurn.md

@@ -0,0 +1,35 @@
+# Function: actionCommandNftBurn()
+
+> **actionCommandNftBurn**(`opts`): `Promise`\<`void`\>
+
+Action the nft burn command.
+
+## Parameters
+
+• **opts**
+
+The options for the command.
+
+• **opts.seed**: `string`
+
+The seed required for signing by the issuer.
+
+• **opts.issuer**: `string`
+
+The issuer address of the NFT.
+
+• **opts.id**: `string`
+
+The id of the NFT to burn in urn format.
+
+• **opts.node**: `string`
+
+The node URL.
+
+• **opts.explorer**: `string`
+
+The explorer URL.
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/reference/functions/actionCommandNftMint.md

@@ -0,0 +1,15 @@
+# Function: actionCommandNftMint()
+
+> **actionCommandNftMint**(`opts`): `Promise`\<`void`\>
+
+Action the nft mint command.
+
+## Parameters
+
+• **opts**: `object` & `ICliOutputOptionsConsole` & `ICliOutputOptionsEnv` & `ICliOutputOptionsJson`
+
+The options for the command.
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/reference/functions/actionCommandNftResolve.md

@@ -0,0 +1,15 @@
+# Function: actionCommandNftResolve()
+
+> **actionCommandNftResolve**(`opts`): `Promise`\<`void`\>
+
+Action the nft resolve command.
+
+## Parameters
+
+• **opts**: `object` & `ICliOutputOptionsConsole` & `ICliOutputOptionsEnv` & `ICliOutputOptionsJson`
+
+The options for the command.
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/reference/functions/actionCommandNftTransfer.md

@@ -0,0 +1,35 @@
+# Function: actionCommandNftTransfer()
+
+> **actionCommandNftTransfer**(`opts`): `Promise`\<`void`\>
+
+Action the nft transfer command.
+
+## Parameters
+
+• **opts**
+
+The options for the command.
+
+• **opts.seed**: `string`
+
+The seed required for signing by the issuer.
+
+• **opts.id**: `string`
+
+The id of the NFT to transfer in urn format.
+
+• **opts.recipient**: `string`
+
+The recipient address of the NFT.
+
+• **opts.node**: `string`
+
+The node URL.
+
+• **opts.explorer**: `string`
+
+The explorer URL.
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/reference/functions/buildCommandNftBurn.md

@@ -0,0 +1,11 @@
+# Function: buildCommandNftBurn()
+
+> **buildCommandNftBurn**(): `Command`
+
+Build the nft burn command for the CLI.
+
+## Returns
+
+`Command`
+
+The command.

package/docs/reference/functions/buildCommandNftMint.md

@@ -0,0 +1,11 @@
+# Function: buildCommandNftMint()
+
+> **buildCommandNftMint**(): `Command`
+
+Build the nft mint command for the CLI.
+
+## Returns
+
+`Command`
+
+The command.

package/docs/reference/functions/buildCommandNftResolve.md

@@ -0,0 +1,11 @@
+# Function: buildCommandNftResolve()
+
+> **buildCommandNftResolve**(): `Command`
+
+Build the nft resolve command for the CLI.
+
+## Returns
+
+`Command`
+
+The command.

package/docs/reference/functions/buildCommandNftTransfer.md

@@ -0,0 +1,11 @@
+# Function: buildCommandNftTransfer()
+
+> **buildCommandNftTransfer**(): `Command`
+
+Build the nft transfer command for the CLI.
+
+## Returns
+
+`Command`
+
+The command.

package/docs/reference/index.md

@@ -0,0 +1,16 @@
+# @twin.org/nft-cli
+
+## Classes
+
+- [CLI](classes/CLI.md)
+
+## Functions
+
+- [buildCommandNftBurn](functions/buildCommandNftBurn.md)
+- [actionCommandNftBurn](functions/actionCommandNftBurn.md)
+- [buildCommandNftMint](functions/buildCommandNftMint.md)
+- [actionCommandNftMint](functions/actionCommandNftMint.md)
+- [buildCommandNftResolve](functions/buildCommandNftResolve.md)
+- [actionCommandNftResolve](functions/actionCommandNftResolve.md)
+- [buildCommandNftTransfer](functions/buildCommandNftTransfer.md)
+- [actionCommandNftTransfer](functions/actionCommandNftTransfer.md)

package/locales/en.json

@@ -0,0 +1,123 @@
+{
+	"commands": {
+		"nft-mint": {
+			"summary": "Mint an NFT.",
+			"description": "Mint an NFT.",
+			"options": {
+				"seed": {
+					"param": "--seed '<'seed'>'",
+					"description": "The seed for the issuer address in hex or base64 used to fund the minting, or start with ! to read environment variable."
+				},
+				"issuer": {
+					"param": "--issuer '<'issuer'>'",
+					"description": "The bech32 address of the NFT issuer, or start with ! to read environment variable."
+				},
+				"tag": {
+					"param": "--tag '<'tag'>'",
+					"description": "The tag for the NFT."
+				},
+				"immutable-json": {
+					"param": "--immutable-json '<'immutable-json'>'",
+					"description": "A JSON file to read which includes the immutable data for the NFT."
+				},
+				"mutable-json": {
+					"param": "--mutable-json '<'mutable-json'>'",
+					"description": "A JSON file to read which includes the mutable data for the NFT."
+				}
+			},
+			"progress": {
+				"mintingNft": "Minting NFT"
+			},
+			"labels": {
+				"issuer": "Issuer",
+				"tag": "Tag",
+				"immutableJsonFilename": "Immutable JSON Filename",
+				"mutableJsonFilename": "Mutable JSON Filename",
+				"immutableJson": "Immutable JSON",
+				"mutableJson": "Mutable JSON",
+				"nftId": "NFT Id"
+			}
+		},
+		"nft-resolve": {
+			"summary": "Resolve an NFT.",
+			"description": "Resolve an NFT.",
+			"options": {
+				"id": {
+					"param": "--id '<'id'>'",
+					"description": "The id for the NFT in urn format."
+				}
+			},
+			"progress": {
+				"resolvingNft": "Resolving NFT"
+			},
+			"labels": {
+				"nft": "NFT",
+				"nftId": "NFT Id"
+			}
+		},
+		"nft-burn": {
+			"summary": "Burn an NFT.",
+			"description": "Burn an NFT.",
+			"options": {
+				"seed": {
+					"param": "--seed '<'seed'>'",
+					"description": "The seed for the issuer address in hex or base64 used to fund the burning, or start with ! to read environment variable."
+				},
+				"issuer": {
+					"param": "--issuer '<'issuer'>'",
+					"description": "The bech32 address of the NFT issuer, or start with ! to read environment variable."
+				},
+				"id": {
+					"param": "--id '<'id'>'",
+					"description": "The id for the NFT in urn format."
+				}
+			},
+			"progress": {
+				"burningNft": "Burning NFT"
+			},
+			"labels": {
+				"issuer": "Issuer",
+				"nftId": "NFT Id"
+			}
+		},
+		"nft-transfer": {
+			"summary": "Transfer an NFT.",
+			"description": "Transfer an NFT.",
+			"options": {
+				"seed": {
+					"param": "--seed '<'seed'>'",
+					"description": "The seed for the issuer address in hex or base64 used to fund the transfer, or start with ! to read environment variable."
+				},
+				"id": {
+					"param": "--id '<'id'>'",
+					"description": "The id for the NFT in urn format."
+				},
+				"recipient": {
+					"param": "--recipient '<'recipient'>'",
+					"description": "The bech32 address of the NFT recipient, or start with ! to read environment variable."
+				}
+			},
+			"progress": {
+				"transferringNft": "Transferring NFT"
+			},
+			"labels": {
+				"recipient": "Recipient",
+				"nftId": "NFT Id"
+			}
+		},
+		"common": {
+			"options": {
+				"node": {
+					"param": "--node '<'url'>'",
+					"description": "The url for the node endpoint, or an environment variable name containing the url."
+				}
+			},
+			"labels": {
+				"did": "DID",
+				"node": "Node",
+				"explorer": "Explorer",
+				"explore": "Explore"
+			}
+		}
+	}
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+	"name": "@twin.org/nft-cli",
+	"version": "0.0.1-next.3",
+	"description": "A command line interface for interacting with the nft connectors",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/twinfoundation/nft.git",
+		"directory": "packages/nft-cli"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"scripts": {
+		"clean": "rimraf dist coverage",
+		"build": "tspc",
+		"merge-locales": "merge-locales",
+		"test": "vitest --run --config ./vitest.config.ts --no-cache",
+		"coverage": "vitest --run --coverage --config ./vitest.config.ts --no-cache",
+		"bundle:esm": "rollup --config rollup.config.mjs --environment MODULE:esm",
+		"bundle:cjs": "rollup --config rollup.config.mjs --environment MODULE:cjs",
+		"bundle": "npm run bundle:esm && npm run bundle:cjs",
+		"docs:clean": "rimraf docs/reference",
+		"docs:generate": "typedoc",
+		"docs": "npm run docs:clean && npm run docs:generate",
+		"dist": "npm run clean && npm run build && npm run merge-locales && npm run test && npm run bundle && npm run docs"
+	},
+	"dependencies": {
+		"@twin.org/core": "next",
+		"@twin.org/crypto": "next",
+		"@twin.org/cli-core": "next",
+		"@twin.org/crypto-cli": "next",
+		"@twin.org/entity": "next",
+		"@twin.org/entity-storage-connector-memory": "next",
+		"@twin.org/nameof": "next",
+		"@twin.org/nft-connector-iota": "0.0.1-next.3",
+		"@twin.org/vault-connector-entity-storage": "next",
+		"@twin.org/vault-models": "next",
+		"@twin.org/wallet-cli": "next",
+		"commander": "12.1.0"
+	},
+	"devDependencies": {
+		"@twin.org/merge-locales": "next",
+		"@twin.org/nameof-transformer": "next",
+		"@types/node": "22.5.5",
+		"@vitest/coverage-v8": "2.1.1",
+		"copyfiles": "2.4.1",
+		"rimraf": "6.0.1",
+		"rollup": "4.22.0",
+		"rollup-plugin-typescript2": "0.36.0",
+		"ts-patch": "3.2.1",
+		"typedoc": "0.26.7",
+		"typedoc-plugin-markdown": "4.2.7",
+		"typescript": "5.6.2",
+		"vitest": "2.1.1"
+	},
+	"main": "./dist/cjs/index.cjs",
+	"module": "./dist/esm/index.mjs",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"require": "./dist/cjs/index.cjs",
+			"import": "./dist/esm/index.mjs",
+			"types": "./dist/types/index.d.ts"
+		}
+	},
+	"files": [
+		"bin",
+		"dist/cjs",
+		"dist/esm",
+		"dist/types",
+		"dist/locales",
+		"locales",
+		"docs"
+	],
+	"bin": {
+		"twin-nft": "bin/index.js"
+	}
+}