@pelican.ts/sdk 0.4.15 → 0.4.16-next.1

package/dist/index.d.ts

@@ -1,17 +1,7 @@
 import { AxiosInstance } from 'axios';
 import WebSocket from 'isomorphic-ws';
 
-type FileObject = {
-    name: string;
-    mode: string;
-    mode_bits: string;
-    size: number;
-    is_file: boolean;
-    is_symlink: boolean;
-    mimetype: string;
-    created_at: string;
-    modified_at: string;
-};
+type ServerSignalOption = "start" | "stop" | "restart" | "kill";
 
 type GenericResponse<T, N extends string = string, M = undefined> = {
     object: N;
@@ -24,7 +14,7 @@ type PaginationMeta = {
     per_page: number;
     current_page: number;
     total_pages: number;
-    links: any;
+    links: unknown;
 };
 type GenericListResponse<T> = {
     object: "list";
@@ -59,20 +49,6 @@ type ServerDatabase$1 = {
 type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 type Nullable<T> = T | null;
 
-type ServerBackup$1 = {
-    uuid: string;
-    is_successful: boolean;
-    is_locked: boolean;
-    name: string;
-    ignored_files: string[];
-    checksum: Nullable<string>;
-    bytes: number;
-    created_at: string;
-    completed_at: Nullable<string>;
-};
-
-type ServerSignalOption = "start" | "stop" | "restart" | "kill";
-
 type ServerLimits = {
     memory: number;
     swap: number;
@@ -103,6 +79,40 @@ type StartupMeta = {
     raw_startup_command: string;
 };
 
+type ServerBackup$1 = {
+    uuid: string;
+    is_successful: boolean;
+    is_locked: boolean;
+    name: string;
+    ignored_files: string[];
+    checksum: Nullable<string>;
+    bytes: number;
+    created_at: string;
+    completed_at: Nullable<string>;
+};
+
+type EggVariable = {
+    name: string;
+    description: string;
+    env_variable: string;
+    default_value: string;
+    server_value: string;
+    is_editable: boolean;
+    rules: string;
+};
+
+type FileObject = {
+    name: string;
+    mode: string;
+    mode_bits: string;
+    size: number;
+    is_file: boolean;
+    is_symlink: boolean;
+    mimetype: string;
+    created_at: string;
+    modified_at: string;
+};
+
 type Schedule = {
     id: number;
     name: string;
@@ -135,14 +145,110 @@ type ScheduleTask = {
     updated_at: Nullable<string>;
 };
 
-type EggVariable = {
-    name: string;
-    description: string;
-    env_variable: string;
-    default_value: string;
-    server_value: string;
-    is_editable: boolean;
-    rules: string;
+type SocketEventPayloadMap = {
+    [SOCKET_EVENT.AUTH_SUCCESS]: undefined;
+    [SOCKET_EVENT.STATUS]: PowerState;
+    [SOCKET_EVENT.CONSOLE_OUTPUT]: string;
+    [SOCKET_EVENT.STATS]: StatsWsJson;
+    [SOCKET_EVENT.DAEMON_ERROR]: undefined;
+    [SOCKET_EVENT.DAEMON_MESSAGE]: string;
+    [SOCKET_EVENT.INSTALL_OUTPUT]: string;
+    [SOCKET_EVENT.INSTALL_STARTED]: undefined;
+    [SOCKET_EVENT.INSTALL_COMPLETED]: undefined;
+    [SOCKET_EVENT.TRANSFER_LOGS]: string;
+    [SOCKET_EVENT.TRANSFER_STATUS]: string;
+    [SOCKET_EVENT.BACKUP_COMPLETED]: BackupCompletedJson;
+    [SOCKET_EVENT.BACKUP_RESTORE_COMPLETED]: undefined;
+    [SOCKET_EVENT.TOKEN_EXPIRING]: undefined;
+    [SOCKET_EVENT.TOKEN_EXPIRED]: undefined;
+    [SOCKET_EVENT.JWT_ERROR]: string;
+};
+type Listener<E extends SOCKET_EVENT> = SocketEventPayloadMap[E] extends undefined ? () => void : (payload: SocketEventPayloadMap[E]) => void;
+type CloseEventLike = Parameters<NonNullable<WebSocket["onclose"]>>[0];
+type ErrorEventLike = Parameters<NonNullable<WebSocket["onerror"]>>[0];
+declare class ServerWebsocket {
+    private readonly r;
+    private readonly serverId;
+    private socket?;
+    private currentToken?;
+    private readonly bus;
+    private debugLogging;
+    private stripColors;
+    private detachMessageListener?;
+    constructor(requester: AxiosInstance, id: string, stripColors?: boolean);
+    on<E extends SOCKET_EVENT>(event: E, listener: Listener<E>): () => void;
+    deregister<E extends SOCKET_EVENT>(event: E, listener: Listener<E>): void;
+    private emit;
+    connect(resumable?: boolean, debugLogging?: boolean): Promise<void>;
+    onSocketDisconnect(handler: (event: CloseEventLike) => void): void;
+    onSocketError(handler: (event: ErrorEventLike) => void): void;
+    makeResumable(disconnectsToo: boolean): void;
+    private attachMessageListener;
+    private handleIncomingMessage;
+    private parseMessage;
+    private normalisePayload;
+    private dispatchMessage;
+    private refreshCredentials;
+    private authenticate;
+    disconnect(): void;
+    requestStats(): void;
+    requestLogs(): void;
+    private send;
+    getStats(): Promise<StatsWsJson>;
+    getLogs(): Promise<string[]>;
+    sendPoweraction(action: ServerSignalOption): void;
+    sendCommand(cmd: string): void;
+}
+
+/**
+ * Source: https://github.com/pterodactyl/panel/blob/1.0-develop/resources/scripts/components/server/events.ts
+ */
+declare enum SOCKET_EVENT {
+    AUTH_SUCCESS = "auth success",
+    DAEMON_MESSAGE = "daemon message",
+    DAEMON_ERROR = "daemon error",
+    INSTALL_OUTPUT = "install output",
+    INSTALL_STARTED = "install started",
+    INSTALL_COMPLETED = "install completed",
+    CONSOLE_OUTPUT = "console output",
+    STATUS = "status",
+    STATS = "stats",
+    TRANSFER_LOGS = "transfer logs",
+    TRANSFER_STATUS = "transfer status",
+    BACKUP_COMPLETED = "backup completed",
+    BACKUP_RESTORE_COMPLETED = "backup restore completed",
+    TOKEN_EXPIRING = "token expiring",
+    TOKEN_EXPIRED = "token expired",
+    JWT_ERROR = "jwt error"
+}
+type BackupCompletedJson = {
+    checksum: string;
+    checksum_type: "sha1";
+    file_size: number;
+    is_successful: boolean;
+    uuid: string;
+};
+type PowerState = "starting" | "stopping" | "running" | "offline";
+type StatsWsJson = {
+    memory_bytes: number;
+    memory_limit_bytes: number;
+    cpu_absolute: number;
+    network: {
+        rx_bytes: number;
+        tx_bytes: number;
+    };
+    state: PowerState;
+    uptime: number;
+    disk_bytes: number;
+};
+
+type ServerAllocation$1 = {
+    id: number;
+    ip: string;
+    ip_alias: Nullable<string>;
+    port: number;
+    notes: Nullable<string>;
+    is_default: boolean;
 };
 
 type ServerSubuser = {
@@ -159,15 +265,6 @@ type ServerSubuser = {
 };
 type SubuserPermission = "activity.read" | "allocation.create" | "allocation.delete" | "allocation.read" | "allocation.update" | "backup.create" | "backup.delete" | "backup.download" | "backup.read" | "backup.restore" | "control.console" | "control.restart" | "control.start" | "control.stop" | "database.create" | "database.delete" | "database.read" | "database.update" | "database.view-password" | "file.archive" | "file.create" | "file.delete" | "file.read" | "file.read-content" | "file.sftp" | "file.update" | "schedule.create" | "schedule.delete" | "schedule.read" | "schedule.update" | "settings.description" | "settings.reinstall" | "settings.rename" | "startup.docker-image" | "startup.read" | "startup.update" | "user.create" | "user.delete" | "user.read" | "user.update" | "websocket.connect";
 
-type ServerAllocation$1 = {
-    id: number;
-    ip: string;
-    ip_alias: Nullable<string>;
-    port: number;
-    notes: Nullable<string>;
-    is_default: boolean;
-};
-
 type Server$1 = {
     server_owner: boolean;
     identifier: string;
@@ -255,103 +352,6 @@ type Permission = {
     keys: Record<string, string>;
 };
 
-type SocketEventPayloadMap = {
-    [SOCKET_EVENT.AUTH_SUCCESS]: undefined;
-    [SOCKET_EVENT.STATUS]: PowerState;
-    [SOCKET_EVENT.CONSOLE_OUTPUT]: string;
-    [SOCKET_EVENT.STATS]: StatsWsJson;
-    [SOCKET_EVENT.DAEMON_ERROR]: undefined;
-    [SOCKET_EVENT.DAEMON_MESSAGE]: string;
-    [SOCKET_EVENT.INSTALL_OUTPUT]: string;
-    [SOCKET_EVENT.INSTALL_STARTED]: undefined;
-    [SOCKET_EVENT.INSTALL_COMPLETED]: undefined;
-    [SOCKET_EVENT.TRANSFER_LOGS]: string;
-    [SOCKET_EVENT.TRANSFER_STATUS]: string;
-    [SOCKET_EVENT.BACKUP_COMPLETED]: BackupCompletedJson;
-    [SOCKET_EVENT.BACKUP_RESTORE_COMPLETED]: undefined;
-    [SOCKET_EVENT.TOKEN_EXPIRING]: undefined;
-    [SOCKET_EVENT.TOKEN_EXPIRED]: undefined;
-    [SOCKET_EVENT.JWT_ERROR]: string;
-};
-type Listener<E extends SOCKET_EVENT> = SocketEventPayloadMap[E] extends undefined ? () => void : (payload: SocketEventPayloadMap[E]) => void;
-type CloseEventLike = Parameters<NonNullable<WebSocket["onclose"]>>[0];
-type ErrorEventLike = Parameters<NonNullable<WebSocket["onerror"]>>[0];
-declare class ServerWebsocket {
-    private readonly r;
-    private readonly serverId;
-    private socket?;
-    private currentToken?;
-    private readonly bus;
-    private debugLogging;
-    private stripColors;
-    private detachMessageListener?;
-    constructor(requester: AxiosInstance, id: string, stripColors?: boolean);
-    on<E extends SOCKET_EVENT>(event: E, listener: Listener<E>): () => void;
-    deregister<E extends SOCKET_EVENT>(event: E, listener: Listener<E>): void;
-    private emit;
-    connect(resumable?: boolean, debugLogging?: boolean): Promise<void>;
-    onSocketDisconnect(handler: (event: CloseEventLike) => void): void;
-    onSocketError(handler: (event: ErrorEventLike) => void): void;
-    makeResumable(disconnectsToo: boolean): void;
-    private attachMessageListener;
-    private handleIncomingMessage;
-    private parseMessage;
-    private normalisePayload;
-    private dispatchMessage;
-    private refreshCredentials;
-    private authenticate;
-    disconnect(): void;
-    requestStats(): void;
-    requestLogs(): void;
-    private send;
-    getStats(): Promise<StatsWsJson>;
-    getLogs(): Promise<string[]>;
-    sendPoweraction(action: ServerSignalOption): void;
-    sendCommand(cmd: string): void;
-}
-
-/**
- * Source: https://github.com/pterodactyl/panel/blob/1.0-develop/resources/scripts/components/server/events.ts
- */
-declare enum SOCKET_EVENT {
-    AUTH_SUCCESS = "auth success",
-    DAEMON_MESSAGE = "daemon message",
-    DAEMON_ERROR = "daemon error",
-    INSTALL_OUTPUT = "install output",
-    INSTALL_STARTED = "install started",
-    INSTALL_COMPLETED = "install completed",
-    CONSOLE_OUTPUT = "console output",
-    STATUS = "status",
-    STATS = "stats",
-    TRANSFER_LOGS = "transfer logs",
-    TRANSFER_STATUS = "transfer status",
-    BACKUP_COMPLETED = "backup completed",
-    BACKUP_RESTORE_COMPLETED = "backup restore completed",
-    TOKEN_EXPIRING = "token expiring",
-    TOKEN_EXPIRED = "token expired",
-    JWT_ERROR = "jwt error"
-}
-type BackupCompletedJson = {
-    checksum: string;
-    checksum_type: "sha1";
-    file_size: number;
-    is_successful: boolean;
-    uuid: string;
-};
-type PowerState = "starting" | "stopping" | "running" | "offline";
-type StatsWsJson = {
-    memory_bytes: number;
-    memory_limit_bytes: number;
-    cpu_absolute: number;
-    network: {
-        rx_bytes: number;
-        tx_bytes: number;
-    };
-    state: PowerState;
-    uptime: number;
-    disk_bytes: number;
-};
-
 declare class Account$1 {
     private readonly r;
     constructor(requester: AxiosInstance);
@@ -372,6 +372,43 @@ declare class Account$1 {
     };
 }
 
+declare class ServerActivity {
+    private readonly r;
+    private readonly id;
+    constructor(r: AxiosInstance, id: string);
+    list: (page?: number, per_page?: number) => Promise<ServerActivityLog[]>;
+}
+
+declare class ServerAllocations {
+    private readonly r;
+    private readonly id;
+    constructor(requester: AxiosInstance, id: string);
+    list: () => Promise<ServerAllocation$1[]>;
+    autoAssign: () => Promise<ServerAllocation$1>;
+    setNotes: (alloc_id: number, notes: string) => Promise<ServerAllocation$1>;
+    setPrimary: (alloc_id: number) => Promise<ServerAllocation$1>;
+    unassign: (alloc_id: number) => Promise<void>;
+}
+
+declare class ServerBackups {
+    private readonly r;
+    private readonly id;
+    constructor(requester: AxiosInstance, id: string);
+    list: (page?: number) => Promise<ServerBackup$1[]>;
+    create: (args: {
+        name?: string;
+        is_locked: boolean;
+        ignored_files: string[];
+    }) => Promise<ServerBackup$1>;
+    info: (backup_uuid: string) => Promise<ServerBackup$1>;
+    downloadGetUrl: (backup_uuid: string) => Promise<string>;
+    download: (backup_uuid: string) => Promise<ArrayBuffer>;
+    delete: (backup_uuid: string) => Promise<void>;
+    rename: (backup_uuid: string, name: string) => Promise<void>;
+    toggleLock: (backup_uuid: string) => Promise<void>;
+    restore: (backup_uuid: string, truncate: boolean) => Promise<void>;
+}
+
 declare class ServerDatabases {
     private readonly r;
     private readonly id;
@@ -448,45 +485,14 @@ declare class ScheduleControl {
     };
 }
 
-declare class ServerAllocations {
-    private readonly r;
-    private readonly id;
-    constructor(requester: AxiosInstance, id: string);
-    list: () => Promise<ServerAllocation$1[]>;
-    autoAssign: () => Promise<ServerAllocation$1>;
-    setNotes: (alloc_id: number, notes: string) => Promise<ServerAllocation$1>;
-    setPrimary: (alloc_id: number) => Promise<ServerAllocation$1>;
-    unassign: (alloc_id: number) => Promise<void>;
-}
-
-declare class ServerUsers {
-    private readonly r;
-    private readonly id;
-    constructor(requester: AxiosInstance, id: string);
-    list: () => Promise<ServerSubuser[]>;
-    create: (email: string, permissions: SubuserPermission[] | string[]) => Promise<ServerSubuser>;
-    info: (user_uuid: string) => Promise<ServerSubuser>;
-    update: (user_uuid: string, permissions: SubuserPermission[] | string[]) => Promise<ServerSubuser>;
-    delete: (user_uuid: string) => Promise<void>;
-}
-
-declare class ServerBackups {
+declare class ServerSettings {
     private readonly r;
     private readonly id;
     constructor(requester: AxiosInstance, id: string);
-    list: (page?: number) => Promise<ServerBackup$1[]>;
-    create: (args: {
-        name?: string;
-        is_locked: boolean;
-        ignored_files: string[];
-    }) => Promise<ServerBackup$1>;
-    info: (backup_uuid: string) => Promise<ServerBackup$1>;
-    downloadGetUrl: (backup_uuid: string) => Promise<string>;
-    download: (backup_uuid: string) => Promise<ArrayBuffer>;
-    delete: (backup_uuid: string) => Promise<void>;
-    rename: (backup_uuid: string, name: string) => Promise<void>;
-    toggleLock: (backup_uuid: string) => Promise<void>;
-    restore: (backup_uuid: string, truncate: boolean) => Promise<void>;
+    rename: (name: string) => Promise<void>;
+    updateDescription: (description: Nullable<string>) => Promise<void>;
+    reinstall: () => Promise<void>;
+    changeDockerImage: (image: string) => Promise<void>;
 }
 
 declare class ServerStartup {
@@ -497,21 +503,15 @@ declare class ServerStartup {
     set: (key: string, value: string) => Promise<StartupParams>;
 }
 
-declare class ServerSettings {
+declare class ServerUsers {
     private readonly r;
     private readonly id;
     constructor(requester: AxiosInstance, id: string);
-    rename: (name: string) => Promise<void>;
-    updateDescription: (description: Nullable<string>) => Promise<void>;
-    reinstall: () => Promise<void>;
-    changeDockerImage: (image: string) => Promise<void>;
-}
-
-declare class ServerActivity {
-    private readonly r;
-    private readonly id;
-    constructor(r: AxiosInstance, id: string);
-    list: (page?: number, per_page?: number) => Promise<ServerActivityLog[]>;
+    list: () => Promise<ServerSubuser[]>;
+    create: (email: string, permissions: SubuserPermission[] | string[]) => Promise<ServerSubuser>;
+    info: (user_uuid: string) => Promise<ServerSubuser>;
+    update: (user_uuid: string, permissions: SubuserPermission[] | string[]) => Promise<ServerSubuser>;
+    delete: (user_uuid: string) => Promise<void>;
 }
 
 declare class ServerClient {
@@ -545,6 +545,19 @@ declare class Client$1 {
     server: (uuid: string) => ServerClient;
 }
 
+/**
+ * Instance of a Humane Pelican User
+ *
+ * @class
+ * @example
+ * You can create account from a raw client
+ * ```ts
+ * import {PelicanAPIClient} from "@pelican.ts/sdk/api"
+ * const client = new PelicanAPIClient(...)
+ * const userData = await client.account.info()
+ * const account = new Account(client, userData)
+ * ```
+ */
 declare class Account {
     private readonly client;
     readonly uuid: string;
@@ -734,14 +747,40 @@ declare class ServerUser {
     delete: () => Promise<void>;
 }
 
+/**
+ * Instance of a Humane Pelican Server
+ *
+ * @class
+ * @example
+ * You can create account from a raw client
+ * ```ts
+ * import {PelicanAPIClient} from "@pelican.ts/sdk/api"
+ * const client = new PelicanAPIClient(...)
+ * const serverData = await client.account.server(...).info()
+ * const server = new Server(client, serverData)
+ * ```
+ */
 declare class Server {
     private readonly client;
+    /**
+     * Whether the user owns the server
+     *
+     * @remarks
+     * Useful for gatekeeping features from subusers
+     */
     readonly ownsServer: boolean;
     readonly identifier: string;
+    /**
+     * ID used by Pelican Application API
+     */
     readonly internalId?: number;
     readonly uuid: string;
     private $name;
     get name(): string;
+    /**
+     * Node name used by this server
+     * @
+     */
     readonly node: string;
     readonly isNodeUnderMaintenance: boolean;
     readonly sftp: {
@@ -806,21 +845,64 @@ declare class Server {
     setStartupVariable: (key: string, value: string) => Promise<StartupParams>;
 }
 
+/**
+ * Pelican User Client
+ *
+ * @class
+ * @param client Pelican API Client
+ */
 declare class Client {
     private readonly client;
     constructor(client: Client$1);
+    /**
+     * Get raw API client
+     */
     get $client(): Client$1;
+    /**
+     * Get user account
+     */
     getAccount: () => Promise<Account>;
+    /**
+     * Get subuser (current user) permissions
+     *
+     * Return data is not compatible with subusers API
+     */
     listPermissions: () => Promise<Record<string, Permission>>;
+    /**
+     * List servers
+     *
+     * @param opts Filtering options (all optional)
+     */
     listServers: (opts?: {
+        /**
+         * Server access type (Default: accessible)
+         *
+         * Variants:
+         * - `accessible` — your servers and servers you have access to as a subuser
+         * - `mine` — only your servers
+         * - `admin` — only servers you have admin access to (excluding yours)
+         * - `admin-all` — all servers you have admin access to
+         */
         type?: "accessible" | "mine" | "admin" | "admin-all";
         page?: number;
         per_page?: number;
         include?: ("egg" | "subusers")[];
     }) => Promise<Server[]>;
+    /**
+     * Get server by UUID
+     *
+     * @param uuid Server UUID
+     * @param include Include additional data
+     */
     getServer: (uuid: string, include?: ("egg" | "subusers")[]) => Promise<Server>;
 }
 
+/**
+ * Creates a Humane Pelican User client
+ * @param url Pelican Panel URL (ex: https://demo.pelican.dev)
+ * @param token Pelican User Token (`pacc...`)
+ * @param suffix API suffix, used if you expose api on a different path
+ */
 declare const createPelicanClient: (url: string, token: string, suffix?: string) => Client;
 
 export { Account, Client, Server, ServerAllocation, ServerBackup, ServerDatabase, ServerFile, ServerSchedule, ServerUser, createPelicanClient };