@pelican.ts/sdk 0.3.4-next.4 → 0.4.0

package/dist/types.d.ts

@@ -1151,7 +1151,7 @@ type Server = {
     limits: ServerLimits;
     invocation: string;
     docker_image: string;
-    egg_features: string[] | null;
+    egg_features: Nullable<string[]>;
     feature_limits: FeatureLimits;
     status: Nullable<unknown>;
     is_suspended: boolean;
@@ -1164,7 +1164,7 @@ type Server = {
             uuid: string;
             name: string;
         }, "egg">;
-        subusers: GenericListResponse<GenericResponse<ServerSubuser, "server_subuser">>;
+        subusers?: GenericListResponse<GenericResponse<ServerSubuser, "server_subuser">>;
     };
 };
 type ServerStats = {
@@ -1199,7 +1199,7 @@ type User = {
     image: string;
     admin: boolean;
     root_admin: boolean;
-    "2fa_enabled": number;
+    "2fa_enabled": boolean;
     created_at: string;
     updated_at: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelican.ts/sdk",
-  "version": "0.3.4-next.4",
+  "version": "0.4.0",
   "description": "Pelican panel SDK for TypeScript",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -11,18 +11,27 @@
       "require": "./dist/index.js",
       "import": "./dist/index.mjs"
     },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "require": "./dist/api/index.js",
+      "import": "./dist/api/index.mjs"
+    },
     "./types": {
       "types": "./dist/types.d.ts"
     }
   },
   "scripts": {
-    "build:code": "tsup src/index.ts --format esm,cjs --dts --target esnext",
+    "build:api": "tsup src/api/index.ts --format esm,cjs --dts --target esnext -d dist/api",
+    "build:humane": "tsup src/index.ts --format esm,cjs --dts --target esnext",
     "build:types": "tsup src/types.ts --dts-only --target esnext",
-    "build": "rm -rf ./dist && npm run build:code && npm run build:types",
+    "build": "rm -rf ./dist && npm run build:api && npm run build:humane && npm run build:types",
     "pub": "npm publish --access=public",
     "pub:next": "npm publish --access=public --tag=next",
     "generate-types": "bun run scripts/create-types.ts",
-    "pipeline": "bun run generate-types && bun run build && bun run pub:next"
+    "pipeline:next": "bun run generate-types && bun run build && bun run pub:next",
+    "pipeline": "bun run generate-types && bun run build && bun run pub",
+    "format": "biome format --no-errors-on-unmatched --files-ignore-unknown=true --write .",
+    "prepare": "husky"
   },
   "keywords": [
     "pterodactyl",
@@ -38,8 +47,10 @@
     "url": "git+https://github.com/m41denx/Pelican.ts"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.3.6",
     "@types/node": "^22.18.12",
     "@types/strip-color": "^0.1.2",
+    "husky": "^9.1.7",
     "tsc-alias": "^1.8.16",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3"

package/src/api/client/types/server.ts

@@ -22,7 +22,7 @@ export type Server = {
     limits: ServerLimits,
     invocation: string,
     docker_image: string,
-    egg_features: string[] | null,
+    egg_features: Nullable<string[]>,
     feature_limits: FeatureLimits,
     status: Nullable<unknown>,
     is_suspended: boolean,
@@ -35,7 +35,7 @@ export type Server = {
             uuid: string,
             name: string
         }, "egg">,
-        subusers: GenericListResponse<GenericResponse<ServerSubuser, "server_subuser">>
+        subusers?: GenericListResponse<GenericResponse<ServerSubuser, "server_subuser">>
     }
 }
 

package/src/api/client/types/user.ts

@@ -8,7 +8,7 @@ export type User = {
     image: string,
     admin: boolean,
     root_admin: boolean,
-    "2fa_enabled": number,
+    "2fa_enabled": boolean,
     created_at: string,
     updated_at: string
 

package/src/api/index.ts

@@ -0,0 +1,17 @@
+import {Client as UserClient} from "@/api/client/client";
+import {Client as AppClient} from "@/api/application/client";
+import {Agent} from "@/api/base/request";
+
+export class PelicanAPIClient extends UserClient {
+    constructor(url: string, token: string, suffix: string = "/api") {
+        const ax = new Agent(url, token, "client", suffix)
+        super(ax.requester)
+    }
+}
+
+export class PelicanAPIApplication extends AppClient {
+    constructor(url: string, token: string, suffix: string = "/api") {
+        const ax = new Agent(url, token, "application", suffix)
+        super(ax.requester)
+    }
+}

package/src/humane/Account.ts

@@ -0,0 +1,84 @@
+import type {Client} from "@/api/client/client";
+import type {User} from "@/api/client/types/user";
+
+
+export class Account {
+    private readonly client: Client
+    readonly uuid: string;
+    readonly username: string;
+    private $email: string;
+    get email() {return this.$email}
+    readonly language: string;
+    readonly image: string;
+    readonly admin: boolean;
+    readonly root_admin: boolean;
+    private $has2faEnabled: boolean;
+    get has2faEnabled() {return this.$has2faEnabled}
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+
+    constructor(client: Client, user: User) {
+        this.client = client
+        this.uuid = user.uuid
+        this.username = user.username
+        this.$email = user.email
+        this.language = user.language
+        this.image = user.image
+        this.admin = user.admin
+        this.root_admin = user.root_admin
+        this.$has2faEnabled = user["2fa_enabled"]
+        this.createdAt = new Date(user.created_at)
+        this.updatedAt = new Date(user.updated_at)
+    }
+
+    updateEmail = async (
+        newEmail: string,
+        password: string
+    ) => {
+        await this.client.account.updateEmail(newEmail, password)
+        this.$email = newEmail
+    }
+
+    updatePassword = async (
+        newPassword: string
+    ) => this.client.account.updatePassword(newPassword)
+
+    listApiKeys = async () => this.client.account.apiKeys.list()
+
+    createApiKey = async (
+        description: string,
+        allowed_ips?: string[]
+    ) => this.client.account.apiKeys.create(description, allowed_ips)
+
+    deleteApiKey = async (
+        identifier: string
+    ) => this.client.account.apiKeys.delete(identifier)
+
+    listSshKeys = async () => this.client.account.sshKeys.list()
+
+    createSshKey = async (
+        name: string,
+        public_key: string
+    ) => this.client.account.sshKeys.create(name, public_key)
+
+    deleteSshKey = async (
+        fingerprint: string
+    ) => this.client.account.sshKeys.delete(fingerprint)
+
+    get2faQR = async () => this.client.account.twoFactor.info()
+
+    enable2fa = async (
+        code: string
+    ) => {
+        const tokens = await this.client.account.twoFactor.enable(code)
+        this.$has2faEnabled = true
+        return tokens
+    }
+
+    disable2fa = async (
+        password: string
+    ) => {
+        await this.client.account.twoFactor.disable(password)
+        this.$has2faEnabled = false
+    }
+}

package/src/humane/Client.ts

@@ -0,0 +1,43 @@
+import type {Client as ClientT} from "@/api/client/client";
+import {Account} from "@/humane/Account";
+import {Server} from "@/humane/Server";
+
+
+export class Client {
+    private readonly client: ClientT
+
+    constructor(client: ClientT) {
+        this.client = client
+    }
+
+    get $client(): ClientT {
+        return this.client
+    }
+
+    getAccount = async () => {
+        const user = await this.client.account.info()
+        return new Account(this.client, user)
+    }
+
+    listPermissions = async () => this.client.listPermissions()
+
+    listServers = async (
+        opts: {
+            type?: "accessible" | "mine" | "admin" | "admin-all",
+            page?: number,
+            per_page?: number,
+            include?: ("egg" | "subusers")[],
+        } = {type: "accessible", page: 1, per_page: 50}
+    ) => {
+        const data = await this.client.listServers(opts.type, opts.page, opts.per_page, opts.include)
+        return data.map(d => new Server(this.client.server(d.uuid), d))
+    }
+
+    getServer = async (
+        uuid: string,
+        include?: ("egg" | "subusers")[]
+    ) => {
+        const server = await this.client.server(uuid).info(include)
+        return new Server(this.client.server(uuid), server)
+    }
+}

package/src/humane/Server.ts

@@ -0,0 +1,217 @@
+import type {ServerClient} from "@/api/client/server";
+import type {ServerBackups} from "@/api/client/server_backups";
+import type {ServerFiles} from "@/api/client/server_files";
+import type {ServerSchedules} from "@/api/client/server_schedules";
+import type {Server as ServerT} from "@/api/client/types/server";
+import { ServerAllocation } from "@/humane/ServerAllocation";
+import {ServerBackup} from "@/humane/ServerBackup";
+import {ServerDatabase} from "@/humane/ServerDatabase";
+import {ServerFile} from "@/humane/ServerFile";
+import {ServerSchedule} from "@/humane/ServerSchedule";
+import {ServerUser} from "@/humane/ServerUser";
+import type {EggVariable, FeatureLimits, ServerLimits, SubuserPermission} from "@/types";
+import type {Nullable} from "@/utils/types";
+
+
+export class Server {
+    private readonly client: ServerClient
+
+    readonly ownsServer: boolean;
+    readonly identifier: string;
+    readonly internalId?: number;
+    readonly uuid: string;
+    private $name: string;
+    get name() {return this.$name}
+    readonly node: string;
+    readonly isNodeUnderMaintenance: boolean;
+    readonly sftp: {
+        ip: string,
+        alias: Nullable<string>,
+        port: number
+    };
+    private $description: string;
+    get description() {return this.$description}
+    readonly limits: ServerLimits;
+    readonly invocation: string;
+    private $dockerImage: string;
+    get dockerImage() {return this.$dockerImage}
+    readonly eggFeatures: Nullable<string[]>;
+    readonly featureLimits: FeatureLimits;
+    readonly status: unknown;
+    readonly isSuspended: boolean;
+    readonly isInstalling: boolean;
+    readonly isTransferring: boolean;
+    readonly allocations: ServerAllocation[]
+    readonly variables: EggVariable[]
+    readonly egg?: {
+        uuid: string,
+        name: string
+    }
+    readonly subusers?: ServerUser[]
+
+    constructor(client: ServerClient, server: ServerT) {
+        this.client = client
+        this.ownsServer = server.server_owner
+        this.identifier = server.identifier
+        this.internalId = server.internal_id
+        this.uuid = server.uuid
+        this.$name = server.name
+        this.node = server.node
+        this.isNodeUnderMaintenance = server.is_node_under_maintenance
+        this.sftp = server.sftp_details
+        this.$description = server.description
+        this.limits = server.limits
+        this.invocation = server.invocation
+        this.$dockerImage = server.docker_image
+        this.eggFeatures = server.egg_features
+        this.featureLimits = server.feature_limits
+        this.status = server.status
+        this.isSuspended = server.is_suspended
+        this.isInstalling = server.is_installing
+        this.isTransferring = server.is_transferring
+        this.allocations = server.relationships.allocations.data.map(d => new ServerAllocation(this.client, d.attributes))
+        this.variables = server.relationships.variables.data.map(d => d.attributes)
+        this.egg = server.relationships.egg?.attributes
+        this.subusers = server.relationships.subusers?.data.map(d => new ServerUser(this.client, d.attributes))
+    }
+
+    rename = async (
+        name: string
+    ) => {
+        await this.client.settings.rename(name)
+        this.$name = name
+    }
+
+    updateDescription = async (
+        description: string
+    ) => {
+        await this.client.settings.updateDescription(description)
+        this.$description = description
+    }
+
+    reinstall = async () => this.client.settings.reinstall()
+
+    changeDockerImage = async (
+        image: string
+    ) => {
+        await this.client.settings.changeDockerImage(image)
+        this.$dockerImage = image
+    }
+
+    getActivityLogs = async (
+        opts: {
+            page?: number,
+            per_page?: number
+        } = {page: 1, per_page: 50}
+    ) => this.client.activity.list(opts.page, opts.per_page)
+
+    websocket = (stripColors: boolean = false) =>
+        this.client.websocket(stripColors)
+
+    getServerStats = async () => this.client.resources()
+
+    runCommand = async (command: string) => this.client.command(command)
+
+    sendPowerSignal = async (
+        signal: "start" | "stop" | "restart" | "kill"
+    ) => this.client.power(signal)
+
+
+
+    getDatabases = async (
+        opts: {
+            include?: ("password")[],
+            page?: number
+        } = {include: [], page: 1}
+    ) => {
+        const data = await this.client.databases.list(opts.include, opts.page)
+        return data.map(d => new ServerDatabase(this.client, d))
+    }
+
+    createDatabase = async (
+        database: string,
+        remote: string
+    ) => {
+        const data = await this.client.databases.create(database, remote)
+        return new ServerDatabase(this.client, data)
+    }
+
+    getSchedules = async () => {
+        const data = await this.client.schedules.list()
+        return data.map(d => new ServerSchedule(this.client, d))
+    }
+
+    createSchedule = async (
+        ...opts: Parameters<ServerSchedules["create"]>
+    ) => {
+        const data = await this.client.schedules.create(...opts)
+        return new ServerSchedule(this.client, data)
+    }
+
+    getBackups = async (
+        page: number = 1
+    ) => {
+        const data = await this.client.backups.list(page)
+        return data.map(d => new ServerBackup(this.client, d))
+    }
+
+    createBackup = async (
+        ...args: Parameters<ServerBackups["create"]>
+    ) => {
+        const data = await this.client.backups.create(...args)
+        return new ServerBackup(this.client, data)
+    }
+
+    getAllocations = async () => {
+        const data = await this.client.allocations.list()
+        return data.map(d => new ServerAllocation(this.client, d))
+    }
+
+    createAllocation = async () => {
+        const data = await this.client.allocations.autoAssign()
+        return new ServerAllocation(this.client, data)
+    }
+
+    getFiles = async (
+        path?: string
+    ) => {
+        const data = await this.client.files.list(path)
+        return data.map(d => new ServerFile(this.client, d))
+    }
+
+    createFolder = async (
+        ...opts: Parameters<ServerFiles["createFolder"]>
+    ) => this.client.files.createFolder(...opts)
+
+    uploadFile = async (
+        ...opts: Parameters<ServerFiles["upload"]>
+    ) => this.client.files.upload(...opts)
+
+    uploadFileGetUrl = async (
+        ...opts: Parameters<ServerFiles["uploadGetUrl"]>
+    ) => this.client.files.uploadGetUrl(...opts)
+
+    pullFileFromRemote = async (
+        ...opts: Parameters<ServerFiles["pullFromRemote"]>
+    ) => this.client.files.pullFromRemote(...opts)
+
+    getUsers = async () => {
+        const data = await this.client.users.list()
+        return data.map(d => new ServerUser(this.client, d))
+    }
+
+    createUser = async (
+        email: string,
+        permissions: SubuserPermission[] | string[]
+    ) => {
+        const data = await this.client.users.create(email, permissions)
+        return new ServerUser(this.client, data)
+    }
+
+    getStartupInfo = async () => this.client.startup.list()
+
+    setStartupVariable = async (
+        key: string,
+        value: string
+    ) => this.client.startup.set(key, value)
+}

package/src/humane/ServerAllocation.ts

@@ -0,0 +1,39 @@
+import type {ServerClient} from "@/api/client/server";
+import type {ServerAllocation as ServerAllocationT} from "@/api/client/types/server_allocation";
+import type {Nullable} from "@/utils/types";
+
+export class ServerAllocation {
+    private readonly client: ServerClient
+    readonly alias: Nullable<string>
+    readonly id: number
+    readonly ip: string
+    private $isDefault: boolean
+    get isDefault() {return this.$isDefault}
+    private $notes: Nullable<string>
+    get notes() {return this.$notes}
+    readonly port: number
+
+    constructor(client: ServerClient, alloc: ServerAllocationT) {
+        this.client = client
+        this.alias = alloc.alias
+        this.id = alloc.id
+        this.ip = alloc.ip
+        this.$isDefault = alloc.is_default
+        this.$notes = alloc.notes
+        this.port = alloc.port
+    }
+
+    setNotes = async (
+        notes: string
+    ) => {
+        const data = await this.client.allocations.setNotes(this.id, notes)
+        this.$notes = data.notes
+    }
+
+    makeDefault = async () => {
+        const data = await this.client.allocations.setPrimary(this.id)
+        this.$isDefault = data.is_default
+    }
+
+    unassign = async () => this.client.allocations.unassign(this.id)
+}

package/src/humane/ServerBackup.ts

@@ -0,0 +1,37 @@
+import type {ServerClient} from "@/api/client/server";
+import type {ServerBackup as ServerBackupT} from "@/api/common/types/server_backup";
+import type {Nullable} from "@/utils/types";
+
+
+export class ServerBackup {
+    private readonly client: ServerClient
+    readonly bytes: number
+    readonly checksum: Nullable<string>
+    readonly completedAt: Nullable<Date>
+    readonly createdAt: Date
+    readonly ignoredFiles: string[]
+    readonly isLocked: boolean
+    readonly isSuccessful: boolean
+    readonly name: string
+    readonly uuid: string
+
+    constructor(client: ServerClient, backup: ServerBackupT) {
+        this.client = client
+        this.bytes = backup.bytes
+        this.checksum = backup.checksum
+        this.completedAt = backup.completed_at ? new Date(backup.completed_at) : null
+        this.createdAt = new Date(backup.created_at)
+        this.ignoredFiles = backup.ignored_files
+        this.isLocked = backup.is_locked
+        this.isSuccessful = backup.is_successful
+        this.name = backup.name
+        this.uuid = backup.uuid
+    }
+    
+
+    downloadGetUrl = async () => this.client.backups.downloadGetUrl(this.uuid)
+
+    download = async () => this.client.backups.download(this.uuid)
+
+    delete = async () => this.client.backups.delete(this.uuid)
+}

package/src/humane/ServerDatabase.ts

@@ -0,0 +1,36 @@
+import type {ServerClient} from "@/api/client/server";
+import type {ServerDatabase as ServerDatabaseT} from "@/api/common/types/server_database";
+// TODO: Check for validity
+
+export class ServerDatabase {
+    private readonly client: ServerClient
+    readonly allowConnectionsFrom: string
+    readonly host: string
+    readonly port: number
+    readonly id: string
+    readonly maxConnections: number
+    readonly name: string
+    private $password?: string
+    get password() {return this.$password}
+    readonly username: string
+
+    constructor(client: ServerClient, database: ServerDatabaseT) {
+        this.client = client
+        this.allowConnectionsFrom = database.connections_from
+        this.host = database.host.address
+        this.port = database.host.port
+        this.id = database.id
+        this.maxConnections = database.max_connections
+        this.name = database.name
+        this.$password = database.relationships?.password.attributes.password
+        this.username = database.username
+    }
+
+
+    rotatePassword = async () => {
+        const data = await this.client.databases.rotatePassword(this.id)
+        this.$password = data.relationships?.password.attributes.password
+    }
+
+    delete = async () => this.client.databases.delete(this.id)
+}

package/src/humane/ServerFile.ts

@@ -0,0 +1,73 @@
+import path from "node:path";
+import type {ServerClient} from "@/api/client/server";
+import type {FileObject} from "@/api/common/types/server_files";
+
+
+export class ServerFile {
+    private readonly client: ServerClient
+    private readonly dir: string
+    private readonly path: string
+    readonly createdAt: Date
+    readonly isFile: boolean
+    readonly isSymlink: boolean
+    readonly mimetype: string
+    readonly mode: string
+    readonly modeBits: string
+    readonly modifiedAt: Date
+    readonly name: string
+    readonly size: number
+
+    constructor(client: ServerClient, file: FileObject, dir: string = "/") {
+        this.client = client
+        this.dir = dir
+        this.createdAt = new Date(file.created_at)
+        this.isFile = file.is_file
+        this.isSymlink = file.is_symlink
+        this.mimetype = file.mimetype
+        this.mode = file.mode
+        this.modeBits = file.mode_bits
+        this.modifiedAt = new Date(file.modified_at)
+        this.name = file.name
+        this.size = file.size
+        this.path = path.join(dir, this.name)
+    }
+
+    get isArchive() {
+        // Maybe mimetype is better
+        return [
+            "zip", "tgz", "tar.gz", "txz", "tar.xz", "tbz2", "tar.bz2"
+        ].some(ext => this.name.endsWith(`.${ext}`))
+    }
+
+    /**
+     * Return the contents of a file. To read binary file (non-editable) use {@link download} instead
+     */
+    contents = async () => this.client.files.contents(this.path)
+
+    downloadGetUrl = async () => this.client.files.downloadGetUrl(this.path)
+
+    download = async () => this.client.files.download(this.path)
+
+    rename = async (
+        newName: string
+    ) => this.client.files.rename(this.dir, [{from: this.name, to: newName}])
+
+    copy = async () => this.client.files.copy(this.path)
+
+    write = async (
+        content: string
+    ) => this.client.files.write(this.path, content)
+
+    compress = async (
+        archive_name?: string,
+        extension?: "zip" | "tgz" | "tar.gz" | "txz" | "tar.xz" | "tbz2" | "tar.bz2"
+    ) => this.client.files.compress(this.dir, [this.name], archive_name, extension)
+
+    decompress = async () => this.client.files.decompress(this.dir, this.name)
+
+    delete = async () => this.client.files.delete(this.dir, [this.name])
+
+    chmod = async (
+        mode: number
+    ) => this.client.files.chmod(this.dir, [{file: this.name, mode}])
+}