Wrapdactyl NPM

⚠️ Project in progress... ⚠️

🐦 Wrapdactyl

Do you know that moment when your scripts are very messy and full of api calls to your pterodactyl panel? Well this is not a problem anymore because wrapdactyl is here. Wrapdactyl is a pterodactyl wrapper which allows you to make api calls by running simple functions. More info about options here

📥 Installation

npm install wrapdactyl

🔧 How to use

Wrapdactyl is a class that requires some parameters in such as panel url client api key and application api key. It could also be customised by setting some options in order to add or remove functions to make your code maximum optimised.

const wrapdactyl = require('wrapdactyl');

const ptero = new wrapdactyl({
    url: 'https://panel.domain.com',    // Panel url
    client: 'ptlc_...',                 // Client api key
    application: 'ptla_...',            // Application api key
    options: {                      // Options to optimise the performance
        cache: true,                // Enable or disable cache
        events: true,               // Enable of disable events
        checkInterval: 5000,        // An interval which checks the status of tokens and panel
        updateCacheInterval: 30000  // An interval which updates cache in case you have it enabled
    }
})

Even if you did the configuration the pterowrapper is not ready to use yet because it has to go trough a check which can be made by calling the async function check() which returns a promise with the status and ping of the pterodactyl panel and the status of the configured api keys.

ptero.check().then(data => {
    console.log('pterodactyl wrapper is ready');
    console.log(data)
})

The option checkInterval offers you the opotunity to check the configuration in an interval of time
Now the wrapper is ready to use! have fun with it 👍

💻 How cache works

⚠️Warning: This function spams your panel api
Cache is a hardware or software component that stores data so that future requests for that data can be served faster. In this case cache can be used only if the option cache is enabled (cache: true). Cache can be stored at the begging of the code by running the updateCache() async function which returns boolean that tells if the cache process is complete or not.

ptero.updateCache().then(() => {
    console.log('cache has been updated')
    
    // Now you have access to
    ptero.users.cache.get('user id');
    ptero.servers.cache.get('server id');
})

Cache isnt always up to date since you can make modifications manually to the servers and/or users, so thats why there is an option called updateCacheInterval which can be set in miliseconds to update the cache in an interval of time.

📅 How events work

Events are actions or occurrences that happen in the system you are programming, which the system tells you about so your code can react to them. To listen to an wrapdactyl event you will have enable events in options and run the function on() which will take a string as first value, beeing the event name and a callback.

ptero.on('Event Name', (data) => console.log(data));

Event Name	Callback input	Description
checkUpdate	1 value	This event runs only when `checkInterval` is configured. It runs the callback when the interval makes a check and returns the status and ping of the panel aswell and the api keys status
cacheUpdate	null	This events runs only when `updateCacheInterval` is configured, and it runs when the interval of time set updates the cache.

Example:

ptero.on('checkUpdate', (data) => {
    console.log('A check has been made!')
    console.log(data)
});

🐛 Catching Errors

Every function can throw errors in case of bad configuration or the wrapper not beeing ready. After the async function is ran you can check if the funtion is complete or had an error by validating the variable "error"

Here is an example how i would catch errors using this wrapper:

// Example...
ptero.any_funtion()
.then(data => {
    if(data?.panelError) 
        console.log(`Panel responded with status ${data.status} and error message is:\n ${data.message.map(x => x.detail).join('\n')}`)
        /* 
        example of panel error: 
        {
            error: true,
            panelError: true,
            status: 404,
            message: [
                {
                code: 'NotFoundHttpException',
                status: '404',
                detail: 'The requested resource could not be found on the server.'
                }
            ]
        }
        */
    else if(data.error) {
        console.log(`Panel is probably offline`)
        /*
        Example of error:
        {
            error: true,
            message: AxiosError: connect ECONNREFUSED 0.0.0.0:00
            at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1195:16) {
                ...
            }
        }
        */
    }
})
.catch(err => {
    // Wrapdactyl errors could be:
    //   - Wrapdactyl not ready
    //   - Invalid configuration/not all required parameters

    console.error(err);

    /*
    Example or wrapdactyl error
    "Wrapdactyl - id of the node must be present"
    */
})

📕 Client Functions

Show permissions:
Retries all available permissions

ptero.client.permissions()

Account details:
Retrieves information about the account

ptero.client.account.fetch()

Update email:
Updates the password of the account

Value 1 - Required - the new email which you want to change into
Value 2 - Required - password of the account

ptero.client.account.updateEmail('newemail@gmail.com', 'password')

Update password:
Updates the email address of the account

Value 1 - Required - The password of the account
Value 2 - Required - The new password which you want to change into

ptero.client.account.updatePassword('password', 'newpassword')

Two-Factor Authentication details:
Generates a TOTP QR code image to allow the setup of 2FA

ptero.client.account.twofa.fetch()

Enable Two-Factor Authentication:
Enables TOTP 2FA using the QR code generated by the function above

Value 1 - Required - The password of the account
Value 2 - Required - The 2fa code generated by Authenticator app

ptero.client.account.twofa.enable('password', '2fa code')

Disable Two-Factor Authentication:
Disables TOTP 2FA on the account

Value 1 - Required - Password of the account

ptero.client.account.twofa.disable('password')

Disable Two-Factor Authentication:
Disables TOTP 2FA on the account

Value 1 - Required - Password of the account

ptero.client.account.twofa.disable('password')

List API keys:
Retries a list of API keys

ptero.client.account.apikeys.fetch()

Create API key:
Generates a new API key

Value 1 - Required - Name of the api key you want to generate
Value 2 - Nullable - The white list ips

ptero.client.account.apikeys.create('name', ['127.0.0.1'])

Delete API key:
Deletes the specified API key

Value 1 - Required - The api key identifier

ptero.client.account.apikeys.delete('apikey')

Server List:
List all your servers

ptero.client.servers.fetchAll()

Server details:
Retrieves information about the specified server

Value 1 - Required - Server id
Value 2 - Nullable - Options Object
- egg - Information about the egg the server uses
- subusers - List of subusers on the server

ptero.client.servers.fetch('server id', { egg: true, subusers: true });

Server Console details:
Generates credentials to establish a websocket

Value 1 - Required - Server id

ptero.client.servers.consoleDetails('server id')

Server websocket:
Connect to the server websocket

Value 1 - Required - Object - Details to establish the websocket
These can be requested from ptero.client.servers.consoleDetails
- Origin - Required - The panel URL
- Token - Required - The token for authentication
- Socket - Required - The actual websocket destination

let websocket_details = await ptero.client.servers.consoleDetails("server id");
let server = new ptero.client.servers.websocket(websocket_details);

// What you can listen to
server.on('connected', async () => {
    console.log('connected')

    // What you can send to the server
    server.power('start'); // start / restart / stop / kill
    server.send('command');
    server.request.logs();
    server.request.stats();
    
    // Close the websocket
    server.close()
});
server.on('status', (status) => console.log(status));
server.on('stats', (stats) => console.log(stats));
server.on('console', (message) => console.log(message));
server.on('deamonError', (message) => console.log(message));

server.on('expiring', (auth) => {
    console.log('Token is about to expire');
    // send a new token to keep the connection alive
    // A new token can be requested by running ptero.client.servers.consoleDetails
    auth("new token");
});
server.on('expired', () => console.log('Token had expired'));
server.on('disconnected', () => console.log('server disconnected'));

// Connect to the server
server.connect().catch(err => console.log(err));

The function server.connect() is an async function that returns "true" if connected and throws an error in case it couldnt connect to the websocket. It is preferable to put this function at the bottom, before you listen to events if you are going to await the function otherwise it wont triger the event "connected".
Here is an example how await connect function could help:

server.on('connected', () => console.log('Server connected'))

await server.connect();
server.power('start');
server.send('command');
server.request.logs();
server.request.stats();

Server Resource usage:
Retrieves resource utilization of the specified server

Value 1 - Required - Server id

ptero.client.servers.resources('server id')

Send command to the server:
Sends a command to the server. The server must be online to send a command to it.

Value 1 - Required - Server id
Value 2 - Required - Command string

ptero.client.servers.sendCommand('server id', 'command')

Change server power state:
Sends a power signal to the server

Value 1 - Required - Server id
Value 2 - Required - Can be only: start, restart, stop, kill

ptero.client.servers.power('server id', 'start')

⏩ Skipped a lot of functions for the future versions.

Rename server:
Renames the server

Value 1 - Required - Server id
Value 2 - Required - New Name of the server

ptero.client.servers.rename('server id', 'name')

Reinstall server:
Reinstalls the server

Value 1 - Required - Server id

ptero.client.servers.reinstall('server id')

📙 Application functions

List users:
Retrieves all users

Value 1 - nullAble - Options object
- servers - List of servers the user has access to

ptero.users.fetchAll({servers: true})

User details:
Retrieves the specified user

Value 1 - Required - Number or string id of the user
Value 2 - nullAble - Options Object
- servers - List of servers the user has access to

ptero.users.fetch(1, {servers: true})

Create user:
Creates a new user

Value 1 - Required - Configuration
- username - Required - string
- email - Required - string
- first_name - Required - string
- last_name - Required - string
- password - nullable - string
- root_admin - nullable - boolean
- language - nullable - string

ptero.users.create({
    username: 'username',
    email: 'email@mail.com',
    first_name: 'firstname',
    last_name: 'lastname',
    password: 'your_password',
    root_admin: false
})

Update user:
Updates the user information

Value 1 - Required - The id of the user
Value 2 - Required - Options Object
- username - Required - string
- email - Required - string
- first_name - Required - string
- last_name - Required - string
- password - nullable - string
- root_admin - nullable - boolean
- language - nullable - string

ptero.users.update(2, {
    username: 'newusername',
    email: 'newemail@email.com',
    first_name: 'firstname',
    last_name: 'lastname',
    password: 'newPassword'
})

Delete user:
Deletes the specified user

Value 1 - Required - The id of the user you want to delte

ptero.users.delete(2)

List nodes:
Retrieves a list of all nodes

Value 1 - nullable - Options Object
- allocations - List of allocations added to the node
- location - Information about the location the node is assigned to
- servers - List of servers on the node

ptero.nodes.fetchAll({
    allocations: true, 
    location: true,
    servers: true
})

Node details:
Retrieves the specified node

Value 1 - Required - Node id
Value 2 - nullable - Options Object
- allocations - List of allocations added to the node
- location - Information about the location the node is assigned to
- servers - List of servers on the node

ptero.nodes.fetch(1, {
    allocations: true, 
    location: true,
    servers: true
})

Node configuration:
Displays the Wings configuration

Value 1 - Required - Node id

ptero.nodes.configuration(1)

Create node:
Creates a new node

Value 1 - Required - Configuration
- public - Nullable - Boolean
- name - Required - String
- description - Nullable - String
- location_id - Required - Number
- fqdn - Required - String
- scheme - Required - String (http/https)
- behind_proxy - Nullable - Boolean
- maintenance_mode - Nullable - Boolean
- memory - Required - Number
- memory_overallocate - Required - Number
- disk - Required - Number
- disk_overallocate - Required - Number
- upload_size - Nullable - Number
- daemon_listen - Required - Number
- deamon_sftp - Required - Number

ptero.nodes.create({
    name: "New Node",
    location_id: 1,
    fqdn: "node1.domain.com",
    scheme: "https",
    memory: 10240,
    memory_overallocate: 0,
    disk: 50000,
    disk_overallocate: 0,
    upload_size: 100,
    daemon_sftp: 2022,
    daemon_listen: 8080
})

Update node:

Value 1 - Required - Node id
Value 2 - Required - Configuration
- public - Nullable - Boolean
- name - Required - String
- description - Nullable - String
- location_id - Required - Number
- fqdn - Required - String
- scheme - Required - String (http/https)
- behind_proxy - Nullable - Boolean
- maintenance_mode - Nullable - Boolean
- memory - Required - Number
- memory_overallocate - Required - Number
- disk - Required - Number
- disk_overallocate - Required - Number
- upload_size - Nullable - Number
- daemon_listen - Required - Number
- deamon_sftp - Required - Number

ptero.nodes.update(1, {
    name: "Updated Node",
    location_id: 1,
    fqdn: "node.domain.com",
    scheme: "https",
    memory: 10240,
    memory_overallocate: 0,
    disk: 50000,
    disk_overallocate: 0,
    upload_size: 100,
    daemon_sftp: 2022,
    daemon_listen: 8080
})

Delete node:
Deletes the specified node

Value 1 - Required - Node id

ptero.nodes.delete(1)

Wings details:
Check wings status

Value 1 - Required - Node id

⚠️ Warning: This is a beta function, it may have bugs, be slow or not work

ptero.wings(1)

List allocations:
Lists allocations added to the node

Value 1 - Required - Node id
Value 2 - Nullable - Options Object
- node - Information about the node the allocation belongs to
- server - Information about the server the allocation belongs to

ptero.nodes.allocations.fetchAll(1, {node: true, server: true})

Create allocation:
Adds an allocation to the node

Value 1 - Required - Node id
Value 2 - Required - Configuration object
- ip - Required - String - IP address for the allocations
- ports - Required - Array with strings - Object containing the ports to add

ptero.nodes.allocations.create(1, {
    ip: "0.0.0.0",
    ports: [
        "25565"
    ]
})

Delete allocation:
Deletes the specified allocation

Value 1 - Required - Node id
Value 2 - Required - Allocation id

ptero.nodes.allocations.delete(1, 1)

List locations:
Retrieves all locations

Value 1 - Nullable - Options object
- nodes - List of nodes assigned to the location
- servers - List of servers in the location

ptero.locations.fetchAll({
    nodes: true,
    servers: true
})

Location details
Retrieves the specified location

Value 1 - Required - Location id
Value 2 - Nullable - Options object
- nodes - List of nodes assigned to the location
- servers - List of servers in the location

ptero.locations.fetch(1, {
    nodes: true,
    servers: true
})

Create location:
Creates a new location

Value 1 - Required - configuration object
- short - Required - String - Location name
- long - Nullable - String - Location description

ptero.locations.create({
    short: 'UK location'
    long: 'nodes that are located in uk'
})

Update location:
Updates the specified location

Value 1 - Required - Location id
Value 1 - Required - configuration object
- short - Required - String - Location name
- long - Nullable - String - Location description

ptero.locations.update(1, {
    short: 'UK'
    long: 'datacenters in uk'
})

Delete location:
Updates the specified location

Value 1 - Required - location id

ptero.locations.delete(1)

List servers:
Retrieves all servers

ptero.servers.fetchAll()

Server details:
Retrieves the specified servervv

Value 1 - Required - server id
Value 2 - Nullable - Options object
- allocation - List of allocations assigned to the server
- user - Information about the server owner
- subusers - List of users added to the server
- pack - Information about the server pack
- nest - Information about the server's egg nest
- egg - Information about the server's egg
- variables - List of server variables
- location - Information about server's node location
- node - Information about the server's node
- databases - List of databases on the server

ptero.servers.fetch(1, {
    allocation: true,
    user: true,
    subusers: true,
    pack: true,
    nest: true,
    egg: true,
    variables: true, 
    location: true,
    node: true,
    databases: true
})

Update Server details:
Updates the server details

Value 1 - Required - Server id
Value 2 - Required - configuration object
- name - required - string - Name for the server
- user - required - number - ID of the user which the server belongs to
- external_id - Nullable - string - External ID of the server
- description - Nullable - string - Description of the server

ptero.serves.update(1, {
    name: "Public Minecraft",
    user: 1,
    external_id: "customid1",
    description: "a minecraft server for everyone"
})

Update server build:
Updates the server build information

Value 1 - Required - Server id
Value 2 - Required - configuration object
- allocation - required - number - ID of primary allocation
- memory - required - number - The maximum amount of memory allowed for this container/server. Setting this to 0 will allow unlimited memory in a container.
- swap - required - number - Setting this to 0 will disable swap space on this server. Setting to -1 will allow unlimited swap.
- io - required - number - IO performance of this server relative to other running containers
- cpu - required - number - Each physical core on the system is considered to be 100%. Setting this value to 0 will allow a server to use CPU time without restrictions.
- disk - required - number - This server will not be allowed to boot if it is using more than this amount of space. If a server goes over this limit while running it will be safely stopped and locked until enough space is available. Set to 0 to allow unlimited disk usage.
- threads - Nullable - number - Enter the specific CPU cores that this process can run on, or leave blank to allow all cores. This can be a single number, or a comma seperated list. Example: 0, 0-1,3, or 0,1,3,4.
- feature_limits - required - configuration object
  - databases - Present - number - The total number of databases a user is allowed to create for this server.
  - backups - Present - number - The total number of allocations a user is allowed to create for this server.
  - allocations - nullable - number - The total number of allocations a user is allowed to create for this server.

ptero.servers.updateBuild(1, {
    "allocation": 1,
    "cpu": 0,
    "memory": 1024,
    "disk": 1024,
    "swap": -1,
    "io": 500,
    "threads": null,
    "feature_limits": {
        "databases": 5,
        "allocations": 5,
        "backups": 2
    }
})

Update server startup:
Updates the server startup information

Value 1 - required - Server id
Value 2 - required - configuration object
- startup - required - string - Edit your server's startup command here.
- environment - present - object - Environment variables that the egg requires/supports
- egg - required - string - ID of the egg to use
- image - required - string - The Docker image to use for this server
- skip_scripts - present - boolean - If enabled, if the Egg has an install script, it will NOT be ran during install.

{
  "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
  "environment": {
    "SERVER_JARFILE": "server.jar",
    "VANILLA_VERSION": "latest"
  },
  "egg": 5,
  "image": "quay.io/pterodactyl/core:java",
  "skip_scripts": false
}

Create server:
Creates a new server

Value 1 - Required - Server configuration object
- name - Required - String
- user - Required - Number
- egg - Required - Number
- docker_image - Required - String
- startup - Required - String
- environment - Required - String
- limits - Required - Object
  - memory - Requried - Number
  - swap - Required - Number
  - disk - Required - Number
  - io - Required - Number
  - cpu - Required - Number
- feature_limits - Required - Object
  - databases - Required - Number
  - backups - Required - Number
- allocation - Required - Object
  - default - Required - allocation

ptero.servers.create({
    "name": "Building",
    "user": 1,
    "egg": 1,
    "docker_image": "quay.io/pterodactyl/core:java",
    "startup": "java -Xms128M -Xmx128M -jar server.jar",
    "environment": {
        "BUNGEE_VERSION": "latest",
        "SERVER_JARFILE": "server.jar"
    },
    "limits": {
        "memory": 128,
        "swap": 0,
        "disk": 512,
        "io": 500,
        "cpu": 100
    },
    "feature_limits": {
        "databases": 5,
        "backups": 1
    },
    "allocation": {
        "default": 17
    }
})

Suspend server:
Suspends the specified server

Value 1 - Required - Server id

ptero.servers.suspend(1)

Unuspend server:
Unsuspends the specified server

Value 1 - Required - Server id

ptero.servers.unsuspend(1)

Delete server:
Deletes the specified server

Value 1 - Required - Server id

ptero.servers.delete(1)

Force delete server:
Forcefully deletes the specified server

ptero.servers.forceDelete(1)

List nests:
Retrieves all nests

Value 1 - Nullable - Options object
- eggs - List of eggs in the nest
- servers - List of servers in the nest

ptero.nests.fetchAll({
    eggs: true, 
    servers: true
})

Nest details:
Retrieves the specified nests

Value 1 - Required - Nest id
Value 2 - Nullable - Options object
- eggs - List of eggs in the nest
- servers - List of servers in the nest

ptero.nests.fetch(1, {
    eggs: true, 
    servers: true,
})

⚙️ Options

soon

pterodactyl wrapper

axios ws

@everything-registry/sub-chunk-3166 @infinitebrahmanuniverse/nolb-wr

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago