v2-0-1.md

Migrating to v2

If you've already used PteroJS then this guide is for you! If not then read it anyway, it may be useful!

First and foremost, make sure you've updated to v2, you can check by running npm info @devnote-dev/pterojs. This package requires NodeJS v14 or above to work, you can check this with npm -v.

Type Expansion

Now that the package is in TypeScript, full TS typings and interfaces support has been made use of, this can be found mainly in the commons directory which includes typings for the whole package, as well as group-specific typings for the application API and client API.

User Structures

The PteroUser and PteroSubUser classes have been renamed to User and SubUser respectively. ClientUser has also been renamed to Account. This is to reflect the models used by Pterodactyl.

Meta

The ClientServerManager#pageData property has been renamed to meta for API consistency.

Parameter Resolution

Parameters that used to accept objects or numbers/strings have been changed to only accept the base type (number or string). This mainly applies to methods such as UserManager#update which accepted a user object in place of the user ID.

  const user = await app.users.fetch(7);
- await app.users.update(user, { ... });
+ await app.users.update(user.id, { ... });

This change was made because of the very little validation that was in place for verifying the provided object. It also allowed for outdated information to be passed along as supplementary values to API requests, leading to bigger issues. These methods have been changed to fetch the updated object resource from the API before continuing with operations.

Permissions

Permission flags have been changed from numbers to strings for consistency with the API. In other words, permission resolution from numeric values is no longer possible.

- const perms = new Permissions(2, 3, 4, 5);
+ const perms = new Permissions(
+    'control.console',
+    'control.start',
+    'control.stop',
+    'control.restart'
+ );

Additionally, you can specify permission groups as method arguments:

const perms = new Permissions(...Permissions.CONTROL);

Available permission groups on the Permissions class are: CONTROL, USERS, FILES, BACKUPS, ALLOCATIONS, STARTUPS, DATABASES, SCHEDULES, SETTINGS, and ADMIN.

The Permissions#has method has been split into hasAny and hasAll. Asterisks (*) now properly work for resolution and represents all permissions. The Permissions#raw property has been renamed to value. The Permissions#toStrings method has been removed as it can be accessed through the Permissions#value property. The Permissions#fromStrings method has been removed as the resolve class method already does this.

Model Properties

The env property for the server creation object has been renamed to environment, and the image property to dockerImage. Previously PteroJS changed these properties internally but it was confusing and was not consistent with the API.

Previous Usage

// don't do this
const server = await app.servers.create({
    name: 'my mc server',
    user: 7,
    egg: 2,
    image: 'ghcr.io/pterodactyl/yolks:java_17',
    startup:
        'java -Xms128M -Xmx{{SERVER_MEMORY}}M -Dterminal.jline=false -Dterminal.ansi=true -jar {{SERVER_JARFILE}}',
    env: {
        MINECRAFT_VERSION: '1.18.2',
        SERVER_JARFILE: 'server.jar',
        BUILD_NUMBER: 'latest',
    },
    featureLimits: {
        allocations: 2,
        backups: 3,
        databases: 0,
    },
    allocation: {
        default: 12,
    },
});

New Usage

// do this!
const server = await app.servers.create({
    name: 'my mc server',
    user: 7,
    egg: 2,
    dockerImage: 'ghcr.io/pterodactyl/yolks:java_17',
    startup:
        'java -Xms128M -Xmx{{SERVER_MEMORY}}M -Dterminal.jline=false -Dterminal.ansi=true -jar {{SERVER_JARFILE}}',
    environment: {
        MINECRAFT_VERSION: '1.18.2',
        SERVER_JARFILE: 'server.jar',
        BUILD_NUMBER: 'latest',
    },
    featureLimits: {
        allocations: 2,
        backups: 3,
    },
    allocation: {
        default: 12,
    },
});

Two Factor

The two-factor methods on the Account class have been renamed to follow proper casing convetions (e.g. get2faCode -> get2FACode). In most cases you only have to capitalize "FA" in your code.

File Actions

The FileManager#download method's functionality has been changed to actually download files now, it's previous functionality has been reimplemented as FileManager#getDownloadURL. This makes downloading files through PteroJS finally possible, and only requires calling the new method (which calls the old method internally).

Example

const server = await client.servers.fetch(4);
// returns the download url, not the download
const url = await server.files.getDownloadURL('config.yml');
console.log(url);

// downloads the 'server.jar' file from the server and writes it to the path
await server.files.download('server.jar', 'jars/server.jar');

PteroJS will assume the destination path is a relative file path from your current working directory unless an absolute path is specified.

The FileManager#upload method has been replaced with the FileManager#getUploadURL method, however, file uploading through PteroJS has not been implemented yet.

The File#isEditable property has been removed; it was never part of the API and doesn't need to be.

Validation Errors

Internal validation handling is starting to be implemented within the package to save time before interacting with the API. These errors are designed to be more specific and useful than other package errors and will be improved as more features come.

Manager Centralisation

The delete method for most structures has been removed, this is because of conflicts with the manager's cache when using the instance instead of the manager.

Example

  const user = await app.users.fetch(6);
- await user.delete();
+ await app.users.delete(user.id);

Other Notes

You can view the whole list of changes in the changelog. Happy coding!

devnote-dev - 21/06/2022