wispjs 2.4.0 → 3.0.0

package/wisp_api/apis/subusers.ts

@@ -1,159 +0,0 @@
-import { WispAPICore } from "./index";
-import type { PaginationData } from "./index";
-
-export type SupportPermissionType = "server:support.update";
-export type ControlPermissionType = "server:control.console" | "server:control.command" | "server:control.start" | "server:control.stop" | "server:control.restart";
-export type SubuserPermissionType = "server:subuser.read" | "server:subuser.update" | "server:subuser.create" | "server:subuser.delete";
-export type AllocationPermissionType = "server:allocation.read" | "server:allocation.update";
-export type StartupPermissionType = "server:startup.read" | "server:startup.update";
-export type DatabasePermissionType = "server:database.read" | "server:database.update" | "server:database.create" | "server:database.update";
-export type FilePermissionType = "server:file.sftp" | "server:file.list" | "server:file.read" | "server:file.write" | "server:file.delete" | "server:file.archive" | "server:file.git" | "server:file.steam_workshop";
-export type SchedulePermissionType = "server:schedule.read" | "server:schedule.update" | "server:schedule.create" | "server:schedule.delete";
-export type BackupPermissionType = "server:backup.read" | "server:backup.update" | "server:backup.create" | "server:backup.delete" | "server:backup.deploy" | "server:backup.download";
-export type DetailsPermissionType = "server:details.read" | "server:details.update";
-export type AuditPermissionType = "server:audit.read";
-export type FastDLPermissionType = "server:fastdl.read" | "server:fastdl.update";
-export type ModPermissionType = "server:mod.read" | "server:mod.update";
-export type MonitorPermissionType = "server:monitor.read" | "server:monitor.update";
-export type ReinstallPermissionType = "server:reinstall.update";
-export type Permission = SupportPermissionType | ControlPermissionType | SubuserPermissionType | AllocationPermissionType | StartupPermissionType | DatabasePermissionType | FilePermissionType | SchedulePermissionType | BackupPermissionType | DetailsPermissionType | AuditPermissionType | FastDLPermissionType | ModPermissionType | MonitorPermissionType | ReinstallPermissionType;
-
-export interface User {
-  object: "user";
-  attributes: {
-    email: string;
-    name_first: string;
-    naem_last: string;
-    has_2fa: boolean;
-  }
-}
-
-export interface Subuser {
-  object: "server_subuser";
-  attributes: {
-    id: number;
-    permissions: Permission[];
-    created_at: string;
-    updated_at: string;
-    relationships: {
-      user: User;
-    }
-  }
-}
-
-export interface GetSubusersResponse {
-  object: "list";
-  data: Subuser[];
-  meta: {
-    pagination: PaginationData;
-  }
-}
-
-export interface GetAllSubuserPermissionsResponse {
-  permissions: Permission[];
-  assignable: Permission[];
-}
-
-/**
- * Handles interfacing with the Subusers API
- *
- * @public
- */
-export class SubusersAPI {
-  constructor(private core: WispAPICore) {}
-
-
-  /**
-   * Lists all Subusers for the Server
-   *
-   * @public
-   */
-  async List(): Promise<GetSubusersResponse> {
-    const response = await this.core.makeRequest("GET", "subusers", { include: "user" });
-    const data: GetSubusersResponse = await response.json();
-
-    return data;
-  }
-
-
-  /**
-   * Retrieves the details for the Subuser
-   *
-   * @param id The ID of the Subuser
-   *
-   * @public
-   */
-  async GetDetails(id: string): Promise<Subuser> {
-    const response = await this.core.makeRequest("GET", `subusers/${id}`, { include: "user" });
-    const data: Subuser = await response.json();
-
-    return data;
-  }
-
-
-  /**
-   * Get all permissions available to Subusers
-   *
-   * @public
-   */
-  async GetAllPermissions(): Promise<GetAllSubuserPermissionsResponse> {
-    const response = await this.core.makeRequest("GET", "subusers/permissions");
-    const data: GetAllSubuserPermissionsResponse = await response.json();
-
-    return data;
-  }
-
-
-  /**
-   * Creates a new Subuser
-   *
-   * @param email The email for the Subuser
-   * @param permissions The Permissions to grant to the Subuser
-   *
-   * @public
-   */
-  async Create(email: string, permissions: Permission[]): Promise<Subuser> {
-    const requestData = {
-      email: email,
-      permissions: permissions
-    }
-
-    const response = await this.core.makeRequest("POST", "subusers", requestData);
-    const data: Subuser = await response.json();
-
-    return data;
-  }
-
-
-  /**
-   * Updates the Subuser
-   *
-   * @param id The ID of the Subuser
-   * @param email The new email of the Subuser
-   * @param permissions The new permissions for the Subuser
-   *
-   * @public
-   */
-  async Update(id: string, email: string, permissions: Permission[]): Promise<Subuser> {
-    const data = {
-      email: email,
-      permissions: permissions
-    }
-
-    const response = await this.core.makeRequest("PATCH", `subusers/${id}`, data);
-    const responseData: Subuser = await response.json();
-
-    return responseData;
-  }
-
-  /**
-   * Deletes the Subuser
-   *
-   * @param id The ID of the Subuser
-   *
-   * @public
-   */
-  async Delete(id: string): Promise<void> {
-    await this.core.makeRequest("DELETE", `subusers/${id}`);
-  }
-}

package/wisp_api/index.ts

@@ -1,57 +0,0 @@
-import { WispAPICore } from "./apis/index.js";
-import { AllocationsAPI } from "./apis/allocations.js";
-import { AuditLogsAPI } from "./apis/audit_log.js";
-import { BackupsAPI } from "./apis/backups.js";
-import { DatabasesAPI } from "./apis/databases.js";
-import { FastDLAPI } from "./apis/fastdl.js";
-import { FilesystemAPI } from "./apis/filesystem.js";
-import { ModsAPI } from "./apis/mods.js";
-import { SchedulesAPI } from "./apis/schedules.js";
-import { ServersAPI } from "./apis/servers.js";
-import { StartupAPI } from "./apis/startup.js";
-import { SubusersAPI } from "./apis/subusers.js";
-
-/**
- * An Interface for the Wisp HTTP API
- *
- * @public
- */
-export class WispAPI {
-  private core: WispAPICore;
-
-  public Allocations: AllocationsAPI;
-  public AuditLogs: AuditLogsAPI;
-  public Backups: BackupsAPI;
-  public Databases: DatabasesAPI;
-  public FastDL: FastDLAPI;
-  public Filesystem: FilesystemAPI;
-  public Mods: ModsAPI;
-  public Schedules: SchedulesAPI;
-  public Servers: ServersAPI;
-  public Startup: StartupAPI;
-  public Subusers: SubusersAPI;
-
-  /**
-   * @param domain The domain name for your panel
-   * @param uuid The UUID of the Server that all future API calls will reference
-   * @param token The panel API token to use for authorization
-   * @param logger The logger to use for all API logging
-   *
-   * @internal
-   */
-  constructor(domain: string, uuid: string, token: string, logger: any) {
-    this.core = new WispAPICore(domain, uuid, token, logger);
-
-    this.Allocations = new AllocationsAPI(this.core);
-    this.AuditLogs = new AuditLogsAPI(this.core);
-    this.Backups = new BackupsAPI(this.core);
-    this.Databases = new DatabasesAPI(this.core);
-    this.FastDL = new FastDLAPI(this.core);
-    this.Filesystem = new FilesystemAPI(this.core);
-    this.Mods = new ModsAPI(this.core);
-    this.Schedules = new SchedulesAPI(this.core);
-    this.Servers = new ServersAPI(this.core);
-    this.Startup = new StartupAPI(this.core);
-    this.Subusers = new SubusersAPI(this.core);
-  }
-}

package/wisp_socket/index.ts

@@ -1,495 +0,0 @@
-import stripAnsi from 'strip-ansi';
-import { WebsocketPool } from "./pool.js"
-import { ConsoleMessage, FilesearchResults } from "./pool"
-import { GitPullData, GitPullResult } from "./pool.js"
-import { GitCloneData, GitCloneResult } from "./pool.js"
-
-import type { WispAPI } from "../wisp_api/index.js"
-
-
-/**
- * The Websocket information returned from the API
- *
- * @param token The token to use when authenticating with the `auth` command in the Websocket
- * @param url The actual URL of the Websocket
- *
- * @internal
- */
-export interface WebsocketInfo {
-    token: string;
-    url: string;
-}
-
-
-export type WebsocketDetailsPreprocessor = (info: WebsocketInfo) => void;
-
-
-export interface WispSocket {
-    pool: WebsocketPool;
-    logger: any;
-    api: WispAPI;
-    url: string | undefined;
-    token: string | undefined;
-    ghToken: string | undefined;
-    consoleCallbacks: ((message: string) => void)[];
-    detailsPreprocessor: WebsocketDetailsPreprocessor | undefined;
-}
-
-
-/**
- * The primary interface to the Websocket API
- *
- * @internal
- */
-export class WispSocket {
-    constructor(logger: any, api: any, ghToken: string | undefined) {
-        this.logger = logger
-        this.api = api
-        this.ghToken = ghToken
-        this.consoleCallbacks = []
-    }
-
-
-    /**
-     * Sets a callback to run on the Websocket Info before saving the details.
-     *
-     * @example
-     * ```js
-     * // Change the URL of the Websocket
-     * wisp.socket.setWebsocketDetailsPreprocessor((info) => {
-     *    info.url = "wss://newurl.com"
-     * })
-     * ```
-     *
-     * @remarks
-     * ℹ️  This can be used to modify the URL or token after its retrieved from the API
-     *
-     * @param preprocessor The callback to run when the data is received from the API
-     *
-     * @public
-     */
-    setWebsocketDetailsPreprocessor(preprocessor: WebsocketDetailsPreprocessor) {
-        this.detailsPreprocessor = preprocessor;
-    }
-
-
-    /**
-     * Creates a new Websocket Pool
-     *
-     * @throws Throws an error if the URL or token are not set yet
-     * @internal
-     */
-    createPool() {
-        if (!this.url || !this.token) {
-            throw new Error("Attempted to create a pool without a URL or token")
-        }
-
-        this.pool = new WebsocketPool(this.url, this.token)
-    }
-
-
-    /**
-     * Requests and saves the Websocket details from the API
-     *
-     * @internal
-     */
-    async setDetails() {
-        try {
-            const websocketInfo: WebsocketInfo = await this.api.Servers.GetWebsocketDetails()
-            if (this.detailsPreprocessor) {
-                this.detailsPreprocessor(websocketInfo);
-            }
-
-            this.url = websocketInfo.url
-            this.token = websocketInfo.token
-
-            this.logger.info("Got Websocket Details.", this.url, this.token)
-        } catch(e) {
-            this.logger.error(`Failed to get websocket details: ${e}`)
-            throw(e)
-        }
-    }
-
-
-    /**
-     * Disconnects from the websocket
-     *
-     * @internal
-     */
-    async disconnect() {
-        if (this.pool) {
-            await this.pool.disconnect()
-        }
-    }
-
-
-    /**
-     * Verifies that the pool is created and ready to use
-     *
-     * @internal
-     */
-    async verifyPool() {
-        if (!this.pool) {
-            await this.setDetails()
-            this.createPool()
-        }
-    }
-
-
-    /**
-     * Searches all file contents for the given query
-     *
-     * @param query The query string to search for
-     * @param timeout How long to wait (in ms) for results before timing out
-     *
-     * @public
-     */
-    async filesearch(query: string, timeout: number = 10000): Promise<FilesearchResults> {
-        this.logger.info("Running filesearch with: ", query)
-        await this.verifyPool()
-
-        return await this.pool.run((worker) => {
-            const socket = worker.socket
-            const logger = worker.logger
-            logger.log("Running filesearch:", query)
-
-            return new Promise<FilesearchResults>((resolve, reject) => {
-                const timeoutObj = setTimeout(() => {
-                    socket.off("filesearch-results")
-                    logger.error("Rejected filesearch: 'Timeout'")
-                    reject()
-                }, timeout)
-
-                socket.once("filesearch-results", (data) => {
-                    clearTimeout(timeoutObj)
-                    resolve(data)
-                })
-
-                socket.emit("filesearch-start", query)
-            })
-        })
-    }
-
-
-    /**
-     * Performs a git pull operation on the given directory
-     *
-     * @param dir The full directory path to perform a pull on
-     * @param timeout In milliseconds, how long to wait before timing out
-     *
-     * @public
-     */
-    async gitPull(dir: string, useAuth: boolean = false, timeout: number = 10000) {
-        await this.verifyPool()
-
-        const pullResult = await this.pool.run((worker) => {
-            const socket = worker.socket
-            const logger = worker.logger
-            logger.log("Running gitPull:", dir)
-
-            return new Promise<GitPullResult>((resolve, reject) => {
-                let isPrivate = false
-                let finished: (success: boolean, output: string) => void
-
-                const timeoutObj = setTimeout(() => {
-                    logger.error("Rejected gitPull: 'Timeout'")
-                    finished(false, "Timeout")
-                }, timeout)
-
-                finished = (success: boolean, output: string) => {
-                    socket.removeAllListeners("git-pull")
-                    socket.removeAllListeners("git-error")
-                    socket.removeAllListeners("git-success")
-
-                    const result: GitPullResult = {
-                        output: output,
-                        isPrivate: isPrivate
-                    }
-
-                    if (success) {
-                        resolve(result)
-                    } else {
-                        logger.error("Rejected gitPull:", dir, output)
-                        reject(output)
-                    }
-
-                    clearTimeout(timeoutObj)
-                }
-
-                const sendRequest = (includeAuth: boolean = false) => {
-                    const data: GitPullData = { dir: dir }
-
-                    if (includeAuth) {
-                        if (!this.ghToken) {
-                            logger.error("No GitHub token set, can't authenticate")
-                            return finished(false, "Authentication is required, but no GitHub token was set. Can't pull!")
-                        }
-
-                        isPrivate = true
-                        data.authkey = this.ghToken
-                    }
-
-                    socket.emit("git-pull", data)
-                }
-
-                socket.once("git-pull", (data) => {
-                    logger.log(`Updating ${data}`)
-                })
-
-                socket.once("git-success", (commit) => {
-                    logger.log(`Addon updated to ${commit}`)
-
-                    if (!commit) {
-                        logger.log("No commit given!")
-                    }
-
-                    finished(true, commit || "")
-                })
-
-                socket.on("git-error", (message) => {
-                    if (message === "Remote authentication required but no callback set") {
-                        logger.log(`Remote authentication required, trying again with authkey: ${dir}`)
-                        sendRequest(true)
-                    } else {
-                        logger.log(`Error updating addon: ${message}`)
-                        finished(false, message)
-                    }
-                })
-
-                sendRequest(useAuth)
-            })
-        })
-
-        return pullResult
-    }
-
-
-    /**
-     * Clones a new Repo to the given directory
-     *
-     * @param url The HTTPS URL of the repository
-     * @param dir The full path of the directory to clone the repository to
-     * @param branch The branch of the repository to clone
-     * @param timeout In milliseconds, how long to wait before timing out
-     *
-     * @public
-     */
-    async gitClone(url: string, dir: string, branch: string, timeout: number = 20000) {
-        await this.verifyPool()
-
-        return await this.pool.run((worker) => {
-            const socket = worker.socket
-            const logger = worker.logger
-            logger.log("Running gitClone:", url, dir, branch)
-
-            return new Promise<GitCloneResult>((resolve, reject) => {
-                let isPrivate = false
-                let finished: (success: boolean, message?: string) => void
-
-                const timeoutObj = setTimeout(() => {
-                    logger.error("Rejected gitClone: 'Timeout'")
-                    finished(false, "Timeout")
-                }, timeout)
-
-                finished = (success: boolean, message?: string) => {
-                    socket.removeAllListeners("git-clone")
-                    socket.removeAllListeners("git-error")
-                    socket.removeAllListeners("git-success")
-
-                    if (success) {
-                        const result: GitCloneResult = {
-                            isPrivate: isPrivate
-                        }
-
-                        resolve(result)
-                    } else {
-                        logger.error("Rejected gitClone:", url, dir, branch, message)
-                        reject(message)
-                    }
-
-                    clearTimeout(timeoutObj)
-                }
-
-                const sendRequest = (includeAuth: boolean = false) => {
-                    const data: GitCloneData = { dir: dir, url: url, branch: branch }
-
-                    if (includeAuth) {
-                        if (!this.ghToken) {
-                            logger.error("No GitHub token set, can't authenticate")
-                            return finished(false, "Authentication is required, but no GitHub token was set. Can't clone!")
-                        }
-
-                        isPrivate = true
-                        data.authkey = this.ghToken
-                    }
-
-                    socket.emit("git-clone", data)
-                }
-
-                socket.once("git-clone", (data) => {
-                    logger.log(`Cloning ${data}`)
-                })
-
-                socket.once("git-success", () => {
-                    logger.log("Project successfully cloned")
-                    finished(true)
-                })
-
-                socket.on("git-error", (message) => {
-                    if (message === "Remote authentication required but no callback set") {
-                        logger.log(`Remote authentication required, trying again with authkey: ${dir}`)
-                        sendRequest(true)
-                    } else {
-                        logger.log("Error cloning repo:", url, dir, branch, message)
-                        finished(false, message)
-                    }
-                })
-
-                sendRequest()
-            })
-        })
-    }
-
-
-    /**
-     * Sets up the console listener worker
-     *
-     * @internal
-     */
-    setupConsoleListener() {
-        this.verifyPool().then(() => {
-            this.pool.run((worker) => {
-                const logger = worker.logger
-                logger.log("Running setupConsoleListener")
-
-                return new Promise<void>((resolve) => {
-                    worker.socket.on("console", (data: ConsoleMessage) => {
-                        const line = data.line
-
-                        if (this.consoleCallbacks.length == 0) {
-                            return resolve()
-                        }
-
-                        this.consoleCallbacks.forEach((callback) => {
-                            try {
-                                callback(line)
-                            } catch(e) {
-                                logger.error("Failed to run console callback", e)
-                            }
-                        })
-                    })
-                })
-            })
-        })
-    }
-
-
-    /**
-     * Adds a new callback that will run any time a console message is rececived
-     *
-     * @param callback The callback to run, takes a single param, `message`, a string
-     *
-     * @public
-     */
-    addConsoleListener(callback: (message: string) => void) {
-        if (this.consoleCallbacks.length == 0) {
-            this.setupConsoleListener()
-        }
-
-        this.consoleCallbacks.push(callback)
-    }
-
-
-    /**
-     * Removes a previously added console message callback
-     *
-     * @param callback The callback function that was previously added
-     *
-     * @public
-     */
-    removeConsoleListener(callback: (message: string) => void) {
-        const index = this.consoleCallbacks.indexOf(callback)
-        if (index == -1) { return }
-
-        this.consoleCallbacks.splice(index, 1)
-    }
-
-
-    /**
-     * Sends a command to the server and then waits until output with the given prefix is seen in a console message
-     *
-     * @example
-     * Runs a custom lua command that will prefix its output with our nonce, then prints the output from that command
-     * ```lua
-     * -- lua/autorun/server/nonce_example.lua
-     * concommand.Add( "myCommand", function( ply, _, args )
-     *     if IsValid( ply ) then return end
-     *
-     *     local nonce = args[1]
-     *     print( nonce .. "Command output" )
-     * end )
-     * ```
-     * ```js
-     * const nonce = "abc123";
-     * const command = `myCommand "${nonce}"`;
-     * try {
-     *     const output = await wisp.socket.sendCommandNonce(nonce, command);
-     *     console.log("Output from command:", output);
-     * catch (error) {
-     *     console.error(error);
-     * }
-     * ```
-     *
-     * @remarks
-     * ℹ️  This is useful if you run code on your Server that will print output with the same prefix, letting you run commands and also receive output for it
-     *
-     * @param nonce The short, unique string that your output will be prefixed with
-     * @param command The full command string to send
-     * @param timeout In milliseconds, how long to wait for output before timing out
-     *
-     * @public
-     */
-    async sendCommandNonce(nonce: string, command: string, timeout: number = 1000) {
-        await this.verifyPool()
-
-        return await this.pool.run((worker) => {
-            const socket = worker.socket
-            const logger = worker.logger
-            logger.log("Running sendCommandNonce: ", nonce, command)
-
-            return new Promise<string>((resolve: Function, reject: Function) => {
-                let output = ""
-                let callback: (data: ConsoleMessage) => void
-
-                const timeoutObj = setTimeout(() => {
-                    logger.error(`Command timed out current output: '${output}'`)
-                    socket.off("console", callback)
-                    logger.log("Rejected sendCommandNonce 'Timeout'", nonce, command)
-                    reject("Timeout")
-                }, timeout)
-
-                callback = (data: ConsoleMessage) => {
-                    const line = data.line
-                    const clean = stripAnsi(line)
-
-                    if (clean.startsWith(nonce)) {
-                        const message = clean.slice(nonce.length)
-
-                        if (message === "Done.") {
-                            socket.off("console", callback)
-                            clearTimeout(timeoutObj)
-
-                            resolve(output)
-                        } else {
-                            output += message
-                            timeoutObj.refresh()
-                        }
-                    }
-                }
-
-                socket.on("console", callback)
-                socket.emit("send command", command)
-            })
-        })
-    }
-}