wispjs 2.1.3 → 2.1.4

package/dist/wisp_api/apis/filesystem.d.ts

@@ -0,0 +1,200 @@
+import { WispAPICore } from "./index";
+import type { PaginationData } from "./index";
+export interface DirectoryFile {
+    object: "file";
+    attributes: {
+        type: "file" | "directory";
+        name: string;
+        size: number;
+        mime: string;
+        symlink: boolean;
+        created_at: string;
+        modified_at: string;
+    };
+}
+export interface DirectoryContents {
+    object: "list";
+    data: DirectoryFile[];
+    meta: {
+        pagination: PaginationData | undefined;
+    };
+}
+export type GetDirectoryContentsErrorCode = "generic.daemon_connection_exception";
+export interface GetDirectoryContentsError {
+    code: GetDirectoryContentsErrorCode;
+    data: {
+        code: number;
+    };
+}
+export interface GetDirectoryContentsFailure {
+    errors: GetDirectoryContentsError[] | undefined;
+}
+/**
+ * The response object for the GetDirectoryContents call
+ *
+ * @remarks
+ * Used in {@link FilesystemAPI.GetDirectoryContents}
+ *
+ * @public
+ */
+export type GetDirectoryContentsResponse = DirectoryContents | GetDirectoryContentsFailure;
+export interface FileReadError {
+    code: string;
+    data: {
+        code: number;
+    };
+}
+export type FileReadResponse = {
+    errors: FileReadError[];
+    content?: never;
+} | {
+    content: string;
+    errors?: never;
+};
+export interface FileWriteRequest {
+    path: string;
+    content: string;
+}
+export interface CopyFileRequest {
+    path: string;
+}
+export interface DownloadFileResponse {
+    url: string;
+}
+export interface RenameFileRequest {
+    path: string;
+    to: string;
+}
+export interface CompressFilesRequest {
+    paths: string[];
+    to: string;
+}
+/**
+ * Handles interaction with the Server's File System
+ *
+ * @public
+ */
+export declare class FilesystemAPI {
+    private core;
+    constructor(core: WispAPICore);
+    /**
+     * Get the Contents of the given Directory
+     *
+     * @param path The path to list
+     *
+     * @throws {@link GetDirectoryContentsErrorCode}
+     *
+     * @public
+     */
+    GetDirectoryContents(path: string): Promise<GetDirectoryContentsResponse>;
+    /**
+     * Creates a Directory with the given path
+     *
+     * @remarks
+     * ⚠️  This will silently fail if the given path is present and invalid or unreachable
+     * ⚠️  This is always relative to the Server's default directory (usually /home/container)
+     *
+     * @param path The full path to the new Directory
+     *
+     * @public
+     */
+    CreateDirectory(path: string): Promise<void>;
+    /**
+     * Retrieves the contents of the File at the given path
+     *
+     * @param path The full path to the File to read (After the /home/container/ part)
+     *
+     * @throws "Server returned error code: {number}"
+     * This error is often thrown if the given path doesn't exist, or is not readable. The error code would be 404.
+     *
+     * @public
+     */
+    ReadFile(path: string): Promise<string>;
+    /**
+     * Writes the given content to the File at the given path
+     *
+     * @remarks
+     * ⚠️  Overwrites the file if it already exists
+     * ⚠️  This function silently fails if the target path is not writeable
+     *
+     * @param path The full path to the File
+     * @param content The full content of the File
+     *
+     * @public
+     */
+    WriteFile(path: string, content: string): Promise<void>;
+    /**
+     * Copies the File at the given path
+     *
+     * @remarks
+     * ⚠️  New copy will be written to the same directory, with a name such as `test.txt` -> `test.txt copy-1643810941850`
+     *
+     * @param path The full path to the File to Copy
+     *
+     * @throws "Unexpected response code, Copy may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the file path didn't exist or wasn't copyable.
+     *
+     * @public
+     */
+    CopyFile(path: string): Promise<void>;
+    /**
+     * Deletes the Files at all of the given paths
+     *
+     * @param paths An array of File Paths to Delete
+     *
+     * @throws "Unexpected response code, Delete may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the file path didn't exist or wasn't deleteable.
+     *
+     * @public
+     */
+    DeleteFiles(paths: string[]): Promise<void>;
+    /**
+     * Retrieves a Download URL for a File
+     *
+     * @remarks
+     * ⚠️  This will return a Download URL even if the given file does not exist
+     *
+     * @param path The full path to the File
+     *
+     * @public
+     */
+    GetFileDownloadURL(path: string): Promise<string>;
+    /**
+     * Renames (or moves) the given File
+     *
+     * @param path The full path to the File
+     * @param to The new path of the File
+     *
+     * @throws "Unexpected response code, Rename may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the source or destination path did not exist or was not reachable
+     *
+     * @public
+     */
+    RenameFile(path: string, to: string): Promise<void>;
+    /**
+     * Compresses the Files at the given paths
+     *
+     * @remarks
+     * ⚠️  The resulting file appears to be unpredictably named?
+     *
+     * @param paths An array of Paths to Compress
+     * @param to The Directory to write the Compressed Files to
+     *
+     * @throws "Unexpected response code, Compress may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the source or destination path did not exist or was not Compressable
+     *
+     * @public
+     */
+    CompressFiles(paths: string[], to: string): Promise<void>;
+    /**
+     * Decompresses the File at the given path
+     *
+     * @param path The full path to the File to Decompress
+     *
+     * @throws "Unexpected response code, Decompress may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the given path did not exist or was not reachable
+     *
+     * @public
+     */
+    DecompressFile(path: string): Promise<void>;
+}

package/dist/wisp_api/apis/filesystem.js

@@ -0,0 +1,182 @@
+/**
+ * Handles interaction with the Server's File System
+ *
+ * @public
+ */
+export class FilesystemAPI {
+    constructor(core) {
+        this.core = core;
+    }
+    /**
+     * Get the Contents of the given Directory
+     *
+     * @param path The path to list
+     *
+     * @throws {@link GetDirectoryContentsErrorCode}
+     *
+     * @public
+     */
+    async GetDirectoryContents(path) {
+        const response = await this.core.makeRequest("GET", "files/directory", { path: path });
+        const data = await response.json();
+        // TODO: Also include the data.code (or handle the 404 case specifically)
+        if ("errors" in data && data.errors) {
+            throw new Error(data.errors[0].code);
+        }
+        return data;
+    }
+    /**
+     * Creates a Directory with the given path
+     *
+     * @remarks
+     * ⚠️  This will silently fail if the given path is present and invalid or unreachable
+     * ⚠️  This is always relative to the Server's default directory (usually /home/container)
+     *
+     * @param path The full path to the new Directory
+     *
+     * @public
+     */
+    async CreateDirectory(path) {
+        await this.core.makeRequest("POST", "files/directory", { path: path });
+    }
+    /**
+     * Retrieves the contents of the File at the given path
+     *
+     * @param path The full path to the File to read (After the /home/container/ part)
+     *
+     * @throws "Server returned error code: {number}"
+     * This error is often thrown if the given path doesn't exist, or is not readable. The error code would be 404.
+     *
+     * @public
+     */
+    async ReadFile(path) {
+        const response = await this.core.makeRequest("GET", "files/read", { path: path });
+        const data = await response.json();
+        if (data.errors) {
+            throw new Error(`Server returned error code: ${data.errors[0].data.code}`);
+        }
+        return data.content;
+    }
+    /**
+     * Writes the given content to the File at the given path
+     *
+     * @remarks
+     * ⚠️  Overwrites the file if it already exists
+     * ⚠️  This function silently fails if the target path is not writeable
+     *
+     * @param path The full path to the File
+     * @param content The full content of the File
+     *
+     * @public
+     */
+    async WriteFile(path, content) {
+        const data = { path: path, content: content };
+        await this.core.makeRequest("POST", "files/write", data);
+    }
+    /**
+     * Copies the File at the given path
+     *
+     * @remarks
+     * ⚠️  New copy will be written to the same directory, with a name such as `test.txt` -> `test.txt copy-1643810941850`
+     *
+     * @param path The full path to the File to Copy
+     *
+     * @throws "Unexpected response code, Copy may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the file path didn't exist or wasn't copyable.
+     *
+     * @public
+     */
+    async CopyFile(path) {
+        const requestData = { path: path };
+        const response = await this.core.makeRequest("POST", "files/copy", requestData);
+        if (response.status != 204) {
+            throw new Error("Unexpected response code, Copy may not have succeeded");
+        }
+    }
+    /**
+     * Deletes the Files at all of the given paths
+     *
+     * @param paths An array of File Paths to Delete
+     *
+     * @throws "Unexpected response code, Delete may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the file path didn't exist or wasn't deleteable.
+     *
+     * @public
+     */
+    async DeleteFiles(paths) {
+        const response = await this.core.makeRequest("POST", "files/delete", { paths: paths });
+        if (response.status != 204) {
+            throw new Error("Unexpected response code, Delete may not have succeeded");
+        }
+    }
+    /**
+     * Retrieves a Download URL for a File
+     *
+     * @remarks
+     * ⚠️  This will return a Download URL even if the given file does not exist
+     *
+     * @param path The full path to the File
+     *
+     * @public
+     */
+    async GetFileDownloadURL(path) {
+        const response = await this.core.makeRequest("GET", "files/download", { path: path });
+        const data = await response.json();
+        return data.url;
+    }
+    /**
+     * Renames (or moves) the given File
+     *
+     * @param path The full path to the File
+     * @param to The new path of the File
+     *
+     * @throws "Unexpected response code, Rename may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the source or destination path did not exist or was not reachable
+     *
+     * @public
+     */
+    async RenameFile(path, to) {
+        const requestData = { path: path, to: to };
+        const response = await this.core.makeRequest("PATCH", "files/rename", requestData);
+        if (response.status != 204) {
+            throw new Error("Unexpected response code, Rename may not have succeeded");
+        }
+    }
+    /**
+     * Compresses the Files at the given paths
+     *
+     * @remarks
+     * ⚠️  The resulting file appears to be unpredictably named?
+     *
+     * @param paths An array of Paths to Compress
+     * @param to The Directory to write the Compressed Files to
+     *
+     * @throws "Unexpected response code, Compress may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the source or destination path did not exist or was not Compressable
+     *
+     * @public
+     */
+    async CompressFiles(paths, to) {
+        const requestData = { paths: paths, to: to };
+        const response = await this.core.makeRequest("POST", "files/compress", requestData);
+        if (response.status != 204) {
+            throw new Error("Unexpected response code, Compress may not have succeeded");
+        }
+    }
+    /**
+     * Decompresses the File at the given path
+     *
+     * @param path The full path to the File to Decompress
+     *
+     * @throws "Unexpected response code, Decompress may not have succeeded"
+     * If the API returns anything other than a 204, something likely went wrong. Most commonly, this is because the given path did not exist or was not reachable
+     *
+     * @public
+     */
+    async DecompressFile(path) {
+        const response = await this.core.makeRequest("POST", "files/decompress", { path: path });
+        if (response.status != 204) {
+            throw new Error("Unexpected response code, Decompress may not have succeeded");
+        }
+    }
+}

package/dist/wisp_api/apis/index.d.ts

@@ -0,0 +1,52 @@
+export type RequestTypes = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface PaginationData {
+    total: number;
+    count: number;
+    perPage: number;
+    currentPage: number;
+    totalPages: number;
+}
+export interface WispAPICore {
+    domain: string;
+    uuid: string;
+    token: string;
+    logger: any;
+}
+/**
+ * The Core of the API, handling low-level operations such as making requests and setting the server UUID
+ *
+ * @public
+ */
+export declare class WispAPICore {
+    constructor(domain: string, uuid: string, token: string, logger: any);
+    /**
+     * Sets the Server UUID
+     *
+     * @remarks
+     * ℹ️  This can be updated at any time, making all future API calls reference the new Server UUID
+     *
+     * @public
+     */
+    setUUID(uuid: string): void;
+    /**
+     * Generates a URL for the given path
+     *
+     * @param path The API path
+     *
+     * @internal
+     */
+    makeURL(path: string): string;
+    /**
+     * Makes a request with the headers and request data set automatically.
+     *
+     * @remarks
+     * The data field is formatted appropriately for whichever request type is given.
+     *
+     * @param method A standared request method.
+     * @param path The API path to send the request to.
+     * @param data The data to include with the request.
+     *
+     * @internal
+     */
+    makeRequest(method: RequestTypes, path: string, data?: any): Promise<Response>;
+}

package/dist/wisp_api/apis/index.js

@@ -0,0 +1,100 @@
+/**
+ * The Core of the API, handling low-level operations such as making requests and setting the server UUID
+ *
+ * @public
+ */
+export class WispAPICore {
+    constructor(domain, uuid, token, logger) {
+        this.domain = domain;
+        this.uuid = uuid;
+        this.token = token;
+        this.logger = logger;
+    }
+    /**
+     * Sets the Server UUID
+     *
+     * @remarks
+     * ℹ️  This can be updated at any time, making all future API calls reference the new Server UUID
+     *
+     * @public
+     */
+    setUUID(uuid) {
+        this.uuid = uuid;
+    }
+    /**
+     * Generates a URL for the given path
+     *
+     * @param path The API path
+     *
+     * @internal
+     */
+    makeURL(path) {
+        return `https://${this.domain}/api/client/servers/${this.uuid}/${path}`;
+    }
+    // TODO: Handle standard field-level error messages:
+    // {"errors":[{"code":"required","detail":"The path field is required","source":{"field":"path"}}]}
+    /**
+     * Makes a request with the headers and request data set automatically.
+     *
+     * @remarks
+     * The data field is formatted appropriately for whichever request type is given.
+     *
+     * @param method A standared request method.
+     * @param path The API path to send the request to.
+     * @param data The data to include with the request.
+     *
+     * @internal
+     */
+    async makeRequest(method, path, data) {
+        let url = this.makeURL(path);
+        const headers = new Headers({
+            "Content-Type": "application/json",
+            "Accept": "application/vnd.wisp.v1+json",
+            "Authorization": `Bearer ${this.token}`,
+            "User-Agent": "WispJS (https://github.com/CFC-Servers/wispjs, 1.0.0)"
+        });
+        const request = async () => {
+            let response;
+            console.log(`${method} -> ${url}`);
+            switch (method) {
+                case "GET":
+                    if (data !== null) {
+                        const params = new URLSearchParams(data);
+                        const uri = new URL(url);
+                        uri.search = params.toString();
+                        url = uri.toString();
+                        console.log(`Updated GET URL: ${url}`);
+                    }
+                    response = await fetch(url, { method: "GET", headers: headers });
+                    break;
+                case "POST":
+                    data = JSON.stringify(data);
+                    response = await fetch(url, { method: "POST", headers: headers, body: data });
+                    break;
+                case "PUT":
+                    data = data ? JSON.stringify(data) : "";
+                    response = await fetch(url, { method: "PUT", headers: headers, body: data });
+                    break;
+                case "PATCH":
+                    data = JSON.stringify(data);
+                    response = await fetch(url, { method: "PATCH", headers: headers, body: data });
+                    break;
+                case "DELETE":
+                    response = await fetch(url, { method: "DELETE", headers: headers });
+                    break;
+                default:
+                    throw new Error(`Invalid method: ${method}`);
+            }
+            if (!response.ok) {
+                const status = response.status;
+                const statusText = response.statusText;
+                this.logger.error(`Request failed: ${method} -> ${url}: ${status} - ${statusText}`);
+                const text = await response.text();
+                this.logger.error(text);
+                throw new Error(`Request failed! Status: ${status} - ${statusText}`);
+            }
+            return response;
+        };
+        return await request();
+    }
+}

package/dist/wisp_api/apis/mods.d.ts

@@ -0,0 +1,40 @@
+import { WispAPICore } from "./index";
+export interface Mod {
+    object: "mod";
+    attributes: {
+        id: number;
+        name: string;
+        description: string;
+        version: string;
+        category: string;
+        install_count: number;
+        server_state: number;
+    };
+}
+export interface GetModsResponse {
+    object: "list";
+    data: Mod[];
+}
+/**
+ * Handles Listing and Installating of Mods
+ *
+ * @public
+ */
+export declare class ModsAPI {
+    private core;
+    constructor(core: WispAPICore);
+    /**
+     * Lists all Mods available to the Server
+     *
+     * @public
+     */
+    List(): Promise<GetModsResponse>;
+    /**
+     * Installs or Uninstalls the Mod with the given id
+     *
+     * @param id The ID of the Mod to Install/Uninstall
+     *
+     * @public
+     */
+    ToggleInstall(id: string): Promise<void>;
+}

package/dist/wisp_api/apis/mods.js

@@ -0,0 +1,30 @@
+/**
+ * Handles Listing and Installating of Mods
+ *
+ * @public
+ */
+export class ModsAPI {
+    constructor(core) {
+        this.core = core;
+    }
+    /**
+     * Lists all Mods available to the Server
+     *
+     * @public
+     */
+    async List() {
+        const response = await this.core.makeRequest("GET", "mods");
+        const data = await response.json();
+        return data;
+    }
+    /**
+     * Installs or Uninstalls the Mod with the given id
+     *
+     * @param id The ID of the Mod to Install/Uninstall
+     *
+     * @public
+     */
+    async ToggleInstall(id) {
+        await this.core.makeRequest("POST", `mods/${id}`);
+    }
+}